From 1252d0e3054323fb680e572ed1435f0847ad4902 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Sat, 19 Sep 2026 13:58:54 -0400 Subject: [PATCH 1/4] fix(lessons): a derived mirror survives the generic note door, by kind not by name (#3734) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Groundwork for step 7, and a data-integrity fix in its own right. Two kinds keep a queryable mirror in `notes.data` derived from their body: snippets and, since milestone 385, lessons. Every read prefers the mirror — deliberately, because parsing markdown to answer what an index can answer is how a hot path rots. So a write that moves the body must move the mirror. #3128 found that hole for snippets and plugged it with a hard-coded `if note.note_type == SNIPPET_NOTE_TYPE`. The plug was correct and did not generalise: lessons arrived with the same design and none of the protection, which is precisely the "don't add a fourth instance" defect #3734 was told to avoid. The cost is higher for a lesson. A stale snippet mirror reports the wrong path. A stale lesson mirror reports the wrong TRIGGER, and the trigger is the whole retrieval story — the lesson goes on firing for the situation it used to name while displaying the one it now names. Silent, and confident. So `update_note` now dispatches through `_mirror_recomposers()`, a note_type -> recomposer table. A kind with a derived mirror is covered by registering it, not by someone remembering to widen an if. `lessons.recompose_data` is the lesson's entry. It recovers the subject with `embeddings.untrigger_title` — new, and deliberately placed beside the join it inverts rather than in the caller that wanted it, because a separator spelled in two files is a separator that will one day be changed in one of them (#3207). `TRIGGER_SEP` is now the one spelling, and `parse_snippet_fields` uses it too; it had the third copy inline. The two inverses stay distinct on purpose: a snippet partitions at the first separator (its name is a symbol), a lesson strips an exact known suffix (its subject may legitimately contain a dash). Different algorithms, one constant, so they cannot disagree about where the seam is. Provenance is DROPPED when the body drops it, which is the opposite call from a snippet's `verification` — that is carried because it was never in the body to delete. The body is the authority; carrying a value the reader just removed is the failure the recompose exists to prevent. Tests: test_snippet_mirror_generic_door.py becomes test_derived_mirror_generic_door.py, since the concern is now plural. The registry property is asserted directly (every kind with a mirror is in the table; the dispatch names no kind inline), plus the lesson cases and the join/inverse round-trip. `fake_lesson` moves to tests/helpers.py — it existed in test_lesson_surfacing.py and a second copy was about to be written — and gains the explicit `None`s `fake_snippet` carries, because update_note reads `verify_with` and a MagicMock is truthy. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy --- src/scribe/services/embeddings.py | 35 ++- src/scribe/services/lessons.py | 40 +++ src/scribe/services/notes.py | 70 +++-- src/scribe/services/snippets.py | 14 +- tests/helpers.py | 28 ++ tests/test_derived_mirror_generic_door.py | 298 ++++++++++++++++++++++ tests/test_lesson_surfacing.py | 19 +- tests/test_snippet_mirror_generic_door.py | 95 ------- 8 files changed, 462 insertions(+), 137 deletions(-) create mode 100644 tests/test_derived_mirror_generic_door.py delete mode 100644 tests/test_snippet_mirror_generic_door.py diff --git a/src/scribe/services/embeddings.py b/src/scribe/services/embeddings.py index 8734ae4..c29baed 100644 --- a/src/scribe/services/embeddings.py +++ b/src/scribe/services/embeddings.py @@ -203,6 +203,12 @@ def embedding_text(title: str | None, body: str | None) -> str: return f"{title}\n{body}".strip() if body else title +# The join between a situation-keyed record's subject and its trigger. A +# CONSTANT because `untrigger_title` below has to spell the same thing to undo +# it, and two literals that must match are one edit away from not matching. +TRIGGER_SEP = " — " + + def trigger_title(subject: str | None, trigger: str | None) -> str: """`{subject} — {trigger}` — the title half of a situation-keyed document. @@ -226,10 +232,37 @@ def trigger_title(subject: str | None, trigger: str | None) -> str: subject = (subject or "").strip() trigger = (trigger or "").strip() if subject and trigger: - return f"{subject} — {trigger}" + return f"{subject}{TRIGGER_SEP}{trigger}" return subject or trigger +def untrigger_title(title: str | None, trigger: str | None) -> str: + """The subject back out of a `trigger_title` — the inverse of the join. + + Kept HERE, beside the join, for the reason the join itself was + consolidated: a separator spelled in two files is a separator that will one + day be changed in one of them. #3207 records the shape — derive it before + the third copy — and an inverse written in a caller is that third copy + wearing a different name. + + Needs the trigger passed in rather than guessing at the separator, because + a subject may legitimately contain an em dash. Given the trigger, the + suffix is exact and the split cannot be wrong. + + Degrades to the whole title when the suffix is absent — a record written + before the join existed, or one with no trigger yet, still answers with + something a human recognises rather than with "". + """ + title = (title or "").strip() + trigger = (trigger or "").strip() + if not trigger: + return title + suffix = f"{TRIGGER_SEP}{trigger}" + if title.endswith(suffix): + return title[: -len(suffix)].strip() + return title + + # --- chunking (#280): the document shape ------------------------------------ # # bge-small reads at most 512 tokens and fastembed silently truncates the rest, diff --git a/src/scribe/services/lessons.py b/src/scribe/services/lessons.py index bb8e8a0..29a7ce4 100644 --- a/src/scribe/services/lessons.py +++ b/src/scribe/services/lessons.py @@ -317,6 +317,46 @@ def compose_data( return data +def recompose_data(note) -> dict: + """Rebuild a lesson's `data` mirror from its own title and body. + + For the GENERIC note door. `update_lesson` composes the mirror itself from + the merged field set and never needs this; a plain `update_note(body=...)` + has no idea the mirror exists and would leave it behind. + + THE COST OF LEAVING IT BEHIND IS HIGHER HERE THAN FOR A SNIPPET. A stale + snippet mirror reports the wrong path. A stale lesson mirror reports the + wrong TRIGGER — and `lesson_trigger` prefers the mirror, so the lesson goes + on being retrieved for the situation it used to name while displaying the + one it now names. The trigger is the entire retrieval story (step 3), so + that is not a degraded record; it is a record that fires at the wrong + moment and looks right when it does. + + The body is the authority and the mirror is derived — already this file's + rule. This is its enforcement on the path that bypasses `update_lesson`. + + The subject comes back out of the title through `untrigger_title`, the + inverse of the join that composed it, rather than by splitting on a + separator spelled a second time here. + """ + from scribe.services.embeddings import untrigger_title + + body = getattr(note, "body", None) or "" + trigger_match = _BODY_TRIGGER_RE.search(body) + trigger = trigger_match.group(1).strip() if trigger_match else "" + what = untrigger_title(getattr(note, "title", None), trigger) + # Sources through the normal read, which already falls back body → + # arose_from_id. A body edit that drops the provenance line should drop + # the mirror's copy too: the body is the authority, and carrying a value + # the reader just deleted is the failure this function exists to prevent. + sources_match = _BODY_SOURCES_RE.search(body) + sources = ( + normalize_sources(_ID_RE.findall(sources_match.group(1))) + if sources_match else [] + ) + return compose_data(what, trigger, sources) + + async def create_lesson( user_id: int, *, diff --git a/src/scribe/services/notes.py b/src/scribe/services/notes.py index 758e963..7a21123 100644 --- a/src/scribe/services/notes.py +++ b/src/scribe/services/notes.py @@ -1,6 +1,6 @@ import logging import re -from collections.abc import Iterable +from collections.abc import Callable, Iterable from datetime import date, datetime, timezone from sqlalchemy import func, or_, select, text @@ -11,14 +11,44 @@ from scribe.models.base import iso logger = logging.getLogger(__name__) -# The fields `snippets.parse_snippet_fields` reads. Writing any of them can -# change what a snippet's derived `data` mirror should say, so update_note -# recomposes the mirror when one moves. Kept here as a set of NAMES rather -# than imported, because it describes update_note's own `fields` dict, not the -# parser's signature. +# The fields a derived `data` mirror is parsed out of. Writing any of them can +# change what the mirror should say, so update_note recomposes it when one +# moves. Kept here as a set of NAMES rather than imported, because it +# describes update_note's own `fields` dict, not any parser's signature. _PARSED_FROM_BODY = frozenset({"title", "body", "tags"}) +def _mirror_recomposers() -> dict[str, Callable[[Note], dict]]: + """note_type -> the function that rebuilds that kind's derived `data`. + + A TABLE rather than a chain of `if note_type == ...`, because the previous + shape tested one constant and the next kind with a derived mirror was + silently not covered — which is exactly what happened: the snippet guard + (#3128) was hard-coded, and lessons arrived in milestone 385 with the same + body-is-authority/`data`-is-mirror design and none of the protection. + + The failure is invisible from here. Nothing raises, nothing logs; the row + simply keeps answering queries from a mirror that no longer matches its + body, and every surface that prefers the mirror — which is all of them, by + design, because parsing markdown to answer what an index can answer is how + a hot path rots — reports the old value confidently. + + Imported inside the function, not at module scope: both services call back + into this module (`update_snippet`/`update_lesson` -> `update_note`), so a + top-level import is a cycle. + """ + from scribe.services.lessons import ( + LESSON_NOTE_TYPE, recompose_data as _lesson_mirror, + ) + from scribe.services.snippets import ( + SNIPPET_NOTE_TYPE, recompose_data as _snippet_mirror, + ) + return { + SNIPPET_NOTE_TYPE: _snippet_mirror, + LESSON_NOTE_TYPE: _lesson_mirror, + } + + # Text fields where EMPTY MEANS NULL (milestone 317). The sweep's whole signal # is `verify_with IS NULL` = "this is a decision, there is nothing to go and # check". An empty string that is not NULL makes a norm look like a constraint @@ -604,23 +634,19 @@ async def update_note( # costs exactly what the sweep exists to catch. if note.verify_with != check_before: note.verified_at = None - # A snippet's `data` is DERIVED from its body — so a write that moves - # the body through this generic door must move the mirror with it - # (#3128). Without this, PATCH /api/notes/ {body} left the - # mirror behind, and snippet_fields PREFERS the mirror: the row went on - # reporting its old repo/path/symbol to prior-art recall while showing - # its new body. `update_snippet` composes the mirror itself and passes - # it explicitly, so an explicit `data` always wins — the caller that - # knows the field set beats the one that can only re-read the body. + # Some kinds derive `data` from their body — so a write that moves the + # body through this generic door must move the mirror with it (#3128). + # Without this, PATCH /api/notes/ {body} left the mirror behind, + # and every read PREFERS the mirror: a snippet went on reporting its + # old repo/path/symbol to prior-art recall while showing its new body, + # and a lesson would go on being retrieved for the situation it used to + # name. The kind's own updater composes the mirror itself and passes it + # explicitly, so an explicit `data` always wins — the caller that knows + # the field set beats the one that can only re-read the body. if "data" not in fields and not _PARSED_FROM_BODY.isdisjoint(fields): - # Imported here, not at module scope: services/snippets.py calls - # back into this module (update_snippet -> update_note), so a - # top-level import is a cycle. - from scribe.services.snippets import ( - SNIPPET_NOTE_TYPE, recompose_data, - ) - if note.note_type == SNIPPET_NOTE_TYPE: - note.data = recompose_data(note) + recompose = _mirror_recomposers().get(note.note_type or "") + if recompose is not None: + note.data = recompose(note) # Auto-set lifecycle timestamps on status transitions if "status" in fields: _now = datetime.now(timezone.utc) diff --git a/src/scribe/services/snippets.py b/src/scribe/services/snippets.py index c36067b..2873f5d 100644 --- a/src/scribe/services/snippets.py +++ b/src/scribe/services/snippets.py @@ -275,9 +275,21 @@ def parse_snippet_fields( ``locations`` is a list of {repo,path,symbol}; ``repo``/``path``/``symbol`` mirror the FIRST location for back-compat with the single-location callers.""" + from scribe.services.embeddings import TRIGGER_SEP + title = title or "" body = body or "" - name, _, when_from_title = title.partition(" — ") + # The inverse of `embeddings.trigger_title`, at the SEPARATOR it composed + # with — imported rather than spelled again, because a separator written + # in two files is a separator that will one day be changed in one of them. + # + # `partition` rather than the `untrigger_title` a lesson uses: that one is + # handed the trigger and strips an exact suffix, which a lesson needs + # because its subject may legitimately contain a dash. A snippet's name is + # a symbol, so the first separator is the right split and no trigger has + # to be known in advance. Two inverses, suited to their callers; one + # constant, so they cannot disagree about where the seam is. + name, _, when_from_title = title.partition(TRIGGER_SEP) fields = { "name": name.strip(), "when_to_use": when_from_title.strip(), diff --git a/tests/helpers.py b/tests/helpers.py index d176e2d..c68f5da 100644 --- a/tests/helpers.py +++ b/tests/helpers.py @@ -191,6 +191,34 @@ def fake_snippet(**attrs) -> MagicMock: }, attrs) +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 check fields and `arose_from_id` are explicitly None for the reason + `fake_snippet`'s `data` is: `update_note` reads `verify_with` and + `expires_when` to decide whether to run the check-field guard, and an + 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("status", None) + attrs.setdefault("arose_from_id", None) + attrs.setdefault("verify_with", None) + attrs.setdefault("expires_when", None) + attrs.setdefault("verified_at", None) + return fake_note(note_type="lesson", **attrs) + + def fake_project(**attrs) -> MagicMock: """design_system_id is explicit: a truthy auto-attribute would route every project through the design-system branch and out to a real database.""" diff --git a/tests/test_derived_mirror_generic_door.py b/tests/test_derived_mirror_generic_door.py new file mode 100644 index 0000000..7d70e68 --- /dev/null +++ b/tests/test_derived_mirror_generic_door.py @@ -0,0 +1,298 @@ +"""A DERIVED `data` mirror survives the GENERIC note door. + +Some kinds store a queryable mirror in `notes.data` that is derived from the +body: a snippet (name, when_to_use, locations…) and a lesson (what, the +trigger, what taught it). Their own updaters compose it from the field set they +just merged, so those were never the problem — the problem is every other way +the body can be written. `update_note` is a `hasattr` loop, and both doors +reach it: PATCH /api/notes/ and the MCP update_note tool. The Knowledge +feed hands you that path, because a card there routes to /notes/:id. + +The failure is silent and the wrong way round, because every read PREFERS the +mirror — deliberately, since parsing markdown to answer what an index can +answer is how a hot path rots. + + - A SNIPPET went on reporting its old repo/path/symbol to the location + reverse lookup and to prior-art recall while displaying its new body: a + record surfaced with full authority and wrong, which the drift-check + docstring calls worse than having no record at all (#3128). + + - A LESSON is worse. Its mirror holds the TRIGGER, and the trigger is the + entire retrieval story — a stale one keeps the lesson firing for the + situation it used to name while it displays the one it now names. + +#3128's fix was correct and did not generalise: it tested one constant, so +milestone 385's lesson arrived with the same design and none of the protection. +The registry tests below assert the PROPERTY — every kind with a derived mirror +is registered — so a third kind fails here rather than shipping quiet (#3734). +""" +import inspect + +import pytest +from tests.helpers import drive_update_note as _update +from tests.helpers import fake_lesson, fake_note, fake_snippet + +OLD_MIRROR = { + "name": "debounce", + "language": "javascript", + "locations": [{"repo": "Scribe", "path": "old/place.js", "symbol": "debounce"}], + "verification": {"status": "ok", "code_sha": "abc", "checked_at": "2026-01-01"}, + "provenance": {"commit_sha": "deadbeef"}, +} + +MOVED_BODY = ( + "**Locations:**\n" + "- `Scribe` · `new/place.ts` · `debounce`\n\n" + "```typescript\nexport const debounce = 1;\n```\n" +) + + +@pytest.mark.asyncio +async def test_a_body_write_moves_the_mirror_with_it(): + note = fake_snippet(data=dict(OLD_MIRROR), project_id=None) + await _update(note, body=MOVED_BODY) + assert note.data["locations"] == [ + {"repo": "Scribe", "path": "new/place.ts", "symbol": "debounce"} + ], "the mirror still describes where the snippet used to live" + assert note.data["language"] == "typescript" + + +@pytest.mark.asyncio +async def test_the_verdict_and_provenance_are_carried_not_dropped(): + """Neither is in the body to parse, so recomposing must carry them. An + ordinary edit must not erase the last drift check — and it needs no + invalidation branch either: `code_sha` is recomputed from the new code, so + a verdict stamped against the old code expires itself on read.""" + note = fake_snippet(data=dict(OLD_MIRROR), project_id=None) + await _update(note, body=MOVED_BODY) + assert note.data["verification"] == OLD_MIRROR["verification"] + assert note.data["provenance"] == OLD_MIRROR["provenance"] + assert note.data["code_sha"] != OLD_MIRROR["verification"]["code_sha"] + + +@pytest.mark.asyncio +async def test_an_explicit_data_wins_over_recomposition(): + """`update_snippet` composes the mirror from the merged field set it holds + and passes it here. That caller knows things the body cannot be re-read for + — which locations were replaced, whether provenance survives the edit — so + an explicit mirror must not be recomputed out from under it.""" + note = fake_snippet(data=dict(OLD_MIRROR), project_id=None) + authoritative = {"name": "from the service", "locations": []} + await _update(note, body=MOVED_BODY, data=authoritative) + assert note.data == authoritative + + +@pytest.mark.asyncio +async def test_a_plain_note_is_left_alone(): + """Only snippets carry a mirror; a note's `data` must not be invented.""" + note = fake_note(note_type="note", data=None, project_id=None) + await _update(note, body="just some prose") + assert note.data is None + + +@pytest.mark.asyncio +async def test_a_write_that_cannot_change_the_parse_does_not_touch_the_mirror(): + """Status, priority, project — none of them is an input to the body parser, + so recomposing on them would be work for nothing and would rebuild a mirror + from a body nobody claimed to have changed.""" + note = fake_snippet(data=dict(OLD_MIRROR), project_id=None) + await _update(note, project_id=4) + assert note.data == OLD_MIRROR + + +@pytest.mark.asyncio +async def test_a_title_change_reaches_the_mirror_too(): + """A snippet's NAME lives in its title, not its body — `parse_snippet_fields` + reads both, so both are triggers.""" + note = fake_snippet(data=dict(OLD_MIRROR), project_id=None) + await _update(note, title="throttle — cap a callback's rate") + assert note.data["name"] == "throttle" + assert note.data["when_to_use"] == "cap a callback's rate" + + +# ── the registry, rather than a chain of ifs ───────────────────────────────── + + +def test_every_kind_with_a_derived_mirror_is_registered(): + """The load-bearing one. Before #3734 this was a single `if` naming + snippets, and the kind added next was simply not covered.""" + from scribe.services.lessons import LESSON_NOTE_TYPE + from scribe.services.notes import _mirror_recomposers + from scribe.services.snippets import SNIPPET_NOTE_TYPE + + table = _mirror_recomposers() + assert SNIPPET_NOTE_TYPE in table, "the #3128 fix was lost" + assert LESSON_NOTE_TYPE in table, ( + "a lesson's `data` holds its trigger and `lesson_trigger` prefers it, " + "so a body edit through the generic door would leave the lesson being " + "retrieved for a situation it no longer names (#3734)" + ) + + +def test_the_dispatch_is_a_lookup_not_a_named_kind(): + """Asserted on structure (rule 167). A lookup extends in one line in one + place; naming a kind inline is the shape that left lessons uncovered.""" + from scribe.services import notes as notes_module + + src = inspect.getsource(notes_module.update_note) + assert "_mirror_recomposers()" in src + assert "SNIPPET_NOTE_TYPE" not in src, ( + "update_note names one kind again — that is the shape #3734 replaced" + ) + + +def test_each_recomposer_takes_the_note_and_nothing_else(): + """A registry entry with the wrong signature fails inside a generic PATCH, + which is the one moment nobody is watching.""" + from scribe.services.notes import _mirror_recomposers + + for kind, fn in _mirror_recomposers().items(): + assert callable(fn), f"{kind} maps to something not callable" + assert len(inspect.signature(fn).parameters) == 1, kind + + +# ── a lesson's mirror moves with its body ──────────────────────────────────── + + +NEW_TRIGGER = "a CI run has sat in_progress far longer than its suite takes" + + +def _lesson_body(trigger, insight="Read the job log.", sources=None): + from scribe.services.lessons import compose_body + return compose_body(insight, trigger, sources) + + +@pytest.mark.asyncio +async def test_a_body_write_moves_a_lessons_trigger_with_it(): + from scribe.services.lessons import TRIGGER_KEY, compose_title + + what = "Read the job log before waiting longer" + note = fake_lesson( + title=compose_title(what, NEW_TRIGGER), + data={TRIGGER_KEY: "a CI run is slow", "what": what}, + project_id=None, + ) + await _update(note, body=_lesson_body(NEW_TRIGGER)) + assert note.data[TRIGGER_KEY] == NEW_TRIGGER, ( + "the mirror kept the old trigger — the lesson would still be retrieved " + "for the situation it no longer names" + ) + assert note.data["what"] == what + + +@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 + + 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, + ) + await _update(note, body=_lesson_body(trigger)) + assert note.data["what"] == what + assert note.data[TRIGGER_KEY] == trigger + + +@pytest.mark.asyncio +async def test_dropping_the_provenance_line_drops_it_from_the_mirror(): + """The body is the authority. Carrying a value the reader just deleted is + 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 + + note = fake_lesson( + title=compose_title("Something learned", "a situation"), + data={SOURCES_KEY: [999]}, + project_id=None, + ) + await _update(note, body=_lesson_body("a situation")) # no Learned from: + assert SOURCES_KEY not in note.data + + +@pytest.mark.asyncio +async def test_an_explicit_data_wins_for_a_lesson_too(): + """`update_lesson` composes the mirror from the merged field set and passes + it here; that caller knows things a re-read of the body cannot recover.""" + from scribe.services.lessons import TRIGGER_KEY + + note = fake_lesson(data={TRIGGER_KEY: "old"}, project_id=None) + authoritative = {TRIGGER_KEY: "from the service", "what": "x"} + await _update(note, body=_lesson_body(NEW_TRIGGER), data=authoritative) + assert note.data == authoritative + + +@pytest.mark.asyncio +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 + + trigger = "two absolute siblings overlap" + note = fake_lesson( + body=_lesson_body(trigger), + data={TRIGGER_KEY: trigger, "what": "the old subject"}, + project_id=None, + ) + await _update(note, title=compose_title("the new subject", trigger)) + assert note.data["what"] == "the new subject" + assert note.data[TRIGGER_KEY] == trigger + + +# ── the join and its inverse ───────────────────────────────────────────────── + + +@pytest.mark.parametrize( + ("subject", "trigger"), + [ + ("a subject", "a trigger"), + ("a subject — with a dash", "a trigger"), + ("a subject", ""), + ("", "a trigger"), + ("a subject", "a trigger — with a dash"), + ], +) +def test_untrigger_title_inverts_trigger_title(subject, trigger): + """#3207's shape: the join had three copies before it was consolidated, so + its inverse lives beside it rather than in whichever caller wanted it.""" + from scribe.services.embeddings import trigger_title, untrigger_title + + title = trigger_title(subject, trigger) + assert untrigger_title(title, trigger) == (subject or trigger).strip() + + +def test_untrigger_title_degrades_to_the_whole_title(): + """A record written before the join existed still answers with something a + human recognises rather than with "".""" + from scribe.services.embeddings import untrigger_title + + assert untrigger_title("a plain old title", "") == "a plain old title" + assert untrigger_title("a plain old title", "a trigger it lacks") == ( + "a plain old title" + ) + + +def test_the_trigger_separator_is_spelled_in_exactly_one_place(): + """Two literals that must match are one edit away from not matching.""" + import pathlib + + root = pathlib.Path(__file__).resolve().parents[1] / "src" / "scribe" + offenders = [ + str(p.relative_to(root)) for p in root.rglob("*.py") + if '" \u2014 "' in p.read_text() and p.name != "embeddings.py" + ] + assert not offenders, ( + f"the trigger separator is spelled inline in {offenders} — use " + f"TRIGGER_SEP, trigger_title or untrigger_title (#3207)" + ) + + +def test_the_mirror_guards_can_fail(): + """Rule 167: shown turning red once.""" + from scribe.services.lessons import TRIGGER_KEY, recompose_data + + bare = fake_lesson(title="just a title", body="no composed lines", data=None) + assert TRIGGER_KEY not in recompose_data(bare) diff --git a/tests/test_lesson_surfacing.py b/tests/test_lesson_surfacing.py index 238e4ad..05f27b1 100644 --- a/tests/test_lesson_surfacing.py +++ b/tests/test_lesson_surfacing.py @@ -22,7 +22,7 @@ from unittest.mock import AsyncMock, MagicMock, patch import pytest from scribe.services import plugin_context as pc from scribe.services.lessons import LESSON_NOTE_TYPE -from tests.helpers import fake_note, writepath_cfg +from tests.helpers import fake_lesson, fake_note, writepath_cfg pytestmark = pytest.mark.usefixtures("_no_supersession") @@ -33,23 +33,6 @@ _CFG = {"enabled": True, "threshold": 0.55, "top_k": 3} _BINDING_PHRASE = "before deciding it does not apply" -def fake_lesson(**attrs): - """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. - """ - 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"}) - return fake_note(note_type=LESSON_NOTE_TYPE, **attrs) - - async def _menu(main_hits, *, lesson_hits=None, reuse_hits=None, cfg=None, exclude_ids=None, rec=None, surf=None): """Run the prompt menu with each query stubbed by the kinds it asks for.""" diff --git a/tests/test_snippet_mirror_generic_door.py b/tests/test_snippet_mirror_generic_door.py deleted file mode 100644 index 30af5e2..0000000 --- a/tests/test_snippet_mirror_generic_door.py +++ /dev/null @@ -1,95 +0,0 @@ -"""A snippet's `data` mirror survives the GENERIC note door. - -`notes.data` is derived from the body. The snippet service always composed it -from the field set it had just merged, so `update_snippet` was never the -problem — the problem was every other way a snippet's body could be written. -`update_note` is a `hasattr` loop with no snippet awareness, and both doors -reach it: PATCH /api/notes/ and the MCP update_note tool. The Knowledge -feed handed you that path, because a snippet card there routed to /notes/:id. - -The failure was silent and the wrong way round: `snippet_fields` PREFERS the -mirror, so the row went on reporting its old repo/path/symbol to the location -reverse lookup and to prior-art recall while displaying its new body — a record -surfaced with full authority and wrong, which the drift-check docstring calls -worse than having no record at all (#3128). -""" -import pytest -from tests.helpers import drive_update_note as _update -from tests.helpers import fake_note, fake_snippet - -OLD_MIRROR = { - "name": "debounce", - "language": "javascript", - "locations": [{"repo": "Scribe", "path": "old/place.js", "symbol": "debounce"}], - "verification": {"status": "ok", "code_sha": "abc", "checked_at": "2026-01-01"}, - "provenance": {"commit_sha": "deadbeef"}, -} - -MOVED_BODY = ( - "**Locations:**\n" - "- `Scribe` · `new/place.ts` · `debounce`\n\n" - "```typescript\nexport const debounce = 1;\n```\n" -) - - -@pytest.mark.asyncio -async def test_a_body_write_moves_the_mirror_with_it(): - note = fake_snippet(data=dict(OLD_MIRROR), project_id=None) - await _update(note, body=MOVED_BODY) - assert note.data["locations"] == [ - {"repo": "Scribe", "path": "new/place.ts", "symbol": "debounce"} - ], "the mirror still describes where the snippet used to live" - assert note.data["language"] == "typescript" - - -@pytest.mark.asyncio -async def test_the_verdict_and_provenance_are_carried_not_dropped(): - """Neither is in the body to parse, so recomposing must carry them. An - ordinary edit must not erase the last drift check — and it needs no - invalidation branch either: `code_sha` is recomputed from the new code, so - a verdict stamped against the old code expires itself on read.""" - note = fake_snippet(data=dict(OLD_MIRROR), project_id=None) - await _update(note, body=MOVED_BODY) - assert note.data["verification"] == OLD_MIRROR["verification"] - assert note.data["provenance"] == OLD_MIRROR["provenance"] - assert note.data["code_sha"] != OLD_MIRROR["verification"]["code_sha"] - - -@pytest.mark.asyncio -async def test_an_explicit_data_wins_over_recomposition(): - """`update_snippet` composes the mirror from the merged field set it holds - and passes it here. That caller knows things the body cannot be re-read for - — which locations were replaced, whether provenance survives the edit — so - an explicit mirror must not be recomputed out from under it.""" - note = fake_snippet(data=dict(OLD_MIRROR), project_id=None) - authoritative = {"name": "from the service", "locations": []} - await _update(note, body=MOVED_BODY, data=authoritative) - assert note.data == authoritative - - -@pytest.mark.asyncio -async def test_a_plain_note_is_left_alone(): - """Only snippets carry a mirror; a note's `data` must not be invented.""" - note = fake_note(note_type="note", data=None, project_id=None) - await _update(note, body="just some prose") - assert note.data is None - - -@pytest.mark.asyncio -async def test_a_write_that_cannot_change_the_parse_does_not_touch_the_mirror(): - """Status, priority, project — none of them is an input to the body parser, - so recomposing on them would be work for nothing and would rebuild a mirror - from a body nobody claimed to have changed.""" - note = fake_snippet(data=dict(OLD_MIRROR), project_id=None) - await _update(note, project_id=4) - assert note.data == OLD_MIRROR - - -@pytest.mark.asyncio -async def test_a_title_change_reaches_the_mirror_too(): - """A snippet's NAME lives in its title, not its body — `parse_snippet_fields` - reads both, so both are triggers.""" - note = fake_snippet(data=dict(OLD_MIRROR), project_id=None) - await _update(note, title="throttle — cap a callback's rate") - assert note.data["name"] == "throttle" - assert note.data["when_to_use"] == "cap a callback's rate" -- 2.54.0 From d36d68a20f06d9cba40a186b8b10454e3229468a Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Sat, 19 Sep 2026 14:02:57 -0400 Subject: [PATCH 2/4] feat(lessons): the REST door a human can actually reach (#3734) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step 7, part two. Milestone 385 built the lesson kind through the MCP tools, which is the agent's surface. The Vue app speaks REST, so a lesson was a record a person could not create, read, edit or retire — rule 27 failing at the door rather than in the view. `/api/lessons` now offers list, create, read, update and trash, plus `/api/lessons/taught-by/` — the reverse of `learned_from`, which the task body calls the direction that gets forgotten and arguably the more useful one: a reader opening an old issue wants to know what was learned from it, and until now the relation was only navigable from the lesson's side. `lessons_taught_by` reads `data[taught_by]` through `path_exists`, the same jsonpath dialect the snippet location lookup uses, so both reverse lookups hit the GIN index (0070) the same way rather than scanning bodies. Share-aware via `readable_notes_clause`: it renders beside a record the caller can already see, so a lesson shared with them belongs there exactly as their own does. THE TRIGGER IS REFUSED WHEN EMPTY, at create and at update. This is the one place the door is not a thin wrapper, and it is deliberate: the service will store a triggerless lesson quite happily — it saves, reads correctly in every listing, and never surfaces. There is nothing to notice afterwards, because it looks exactly like a lesson that works. Better to refuse it than to hand back a record that looks finished. The refusal says why, so the next reader does not take it for a nag and delete it. `lesson_to_dict` moves into the service and the MCP tool's `_to_dict` becomes an alias for it. Both doors now return one shape — a payload spelled once per door answers the two of them differently the first time a field is added — and both compose through `services/lessons.py`, so a lesson written from the web ranks identically to one written by an agent. The document IS what ranks, so that parity is the whole reason the door is thin. The dedup gate matches the MCP path: two lessons under one trigger compete in a single ranked list for one reserved slot, so a duplicate here displaces rather than merely clutters. NOT DONE YET: this is the door, not the UI. #3734 stays in_progress until the Vue views, the router entries, the Knowledge browse badge and the both-ways sources panel exist — rule 27 is about the operator being able to touch it. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy --- src/scribe/app.py | 2 + src/scribe/mcp/tools/lessons.py | 19 +-- src/scribe/routes/lessons.py | 251 ++++++++++++++++++++++++++++++++ src/scribe/services/lessons.py | 75 ++++++++++ tests/test_lesson_rest_door.py | 246 +++++++++++++++++++++++++++++++ 5 files changed, 578 insertions(+), 15 deletions(-) create mode 100644 src/scribe/routes/lessons.py create mode 100644 tests/test_lesson_rest_door.py diff --git a/src/scribe/app.py b/src/scribe/app.py index 4b32508..8f82ac6 100644 --- a/src/scribe/app.py +++ b/src/scribe/app.py @@ -32,6 +32,7 @@ from scribe.routes.trash import trash_bp from scribe.routes.dashboard import dashboard_bp from scribe.routes.systems import systems_bp from scribe.routes.canonical_systems import canonical_systems_bp +from scribe.routes.lessons import lessons_bp from scribe.routes.snippets import snippets_bp from scribe.routes.webhooks import webhooks_bp from scribe.mcp import mount_mcp @@ -92,6 +93,7 @@ def create_app() -> Quart: app.register_blueprint(search_bp) app.register_blueprint(profile_bp) app.register_blueprint(knowledge_bp) + app.register_blueprint(lessons_bp) app.register_blueprint(rulebooks_bp) app.register_blueprint(plugin_bp) app.register_blueprint(design_systems_bp) diff --git a/src/scribe/mcp/tools/lessons.py b/src/scribe/mcp/tools/lessons.py index 9409b04..05bd134 100644 --- a/src/scribe/mcp/tools/lessons.py +++ b/src/scribe/mcp/tools/lessons.py @@ -20,21 +20,10 @@ from scribe.mcp.tools import systems as systems_tools from scribe.services.note_usage import record_pulled -def _to_dict(note) -> dict: - """A lesson as the tools return it — the composed fields read back out, - not the raw row, so a caller sees the same vocabulary it wrote with.""" - return { - "id": note.id, - "title": note.title, - "body": note.body, - "when_to_apply": lessons_svc.lesson_trigger(note), - "learned_from": lessons_svc.lesson_sources(note), - "tags": list(note.tags or []), - "project_id": note.project_id, - "note_type": note.note_type, - "created_at": note.created_at.isoformat() if note.created_at else None, - "updated_at": note.updated_at.isoformat() if note.updated_at else None, - } +# The payload shape lives in the service (`lesson_to_dict`), shared with the +# REST door — a shape spelled once per door answers the two of them +# differently the first time a field is added. +_to_dict = lessons_svc.lesson_to_dict async def list_lessons( diff --git a/src/scribe/routes/lessons.py b/src/scribe/routes/lessons.py new file mode 100644 index 0000000..0157f14 --- /dev/null +++ b/src/scribe/routes/lessons.py @@ -0,0 +1,251 @@ +"""REST routes for lessons — a transferable insight, retrievable by situation. + +A lesson is a note with note_type='lesson' (see services/lessons.py). These +routes feed the web UI; the MCP tools (mcp/tools/lessons.py) are the +agent-facing surface. Both go through services/lessons.py, so the compose/parse +contract and the `data` mirror live in one place — the same division snippets +use, and for the same reason: two doors that each compose a lesson would +compose it two ways, and the document IS what ranks. + +ACL (rule #78): reads and writes of a single lesson resolve through the +share-aware `get_lesson` / `can_write_note`, and writes are performed as the +OWNER so a shared editor isn't rejected by the owner-scoped service — +mirroring routes/snippets.py and routes/notes.py. + +WHY THE TRIGGER IS A NAMED FIELD HERE TOO. The web editor could have posted a +body and let the service parse it. It doesn't, because the evidence behind +this kind (step 1) is that a trigger gets filled when a door ASKS for it by +name — the snippet corpus is at 100% on its trigger with no guard anywhere, +because a service composes the title from a parameter. A form that offered one +markdown box would be the option milestone 385 rejected, wearing a different +hat. +""" +import logging + +from quart import Blueprint, jsonify, request + +from scribe.auth import get_current_user_id, login_required +from scribe.routes.utils import not_found, parse_pagination +from scribe.services import dedup as dedup_svc +from scribe.services import knowledge as knowledge_svc +from scribe.services import lessons as lessons_svc +from scribe.services import systems as systems_svc +from scribe.services import trash as trash_svc +from scribe.services.access import ( + can_write_note, + describe_provenance, + label_shared_items, +) +from scribe.services.note_usage import empty_usage, record_pulled, usage_for_notes + +logger = logging.getLogger(__name__) + +lessons_bp = Blueprint("lessons", __name__, url_prefix="/api/lessons") + + +@lessons_bp.route("", methods=["GET"]) +@login_required +async def list_lessons_route(): + """The kind enumerated, rather than only what a query resembles. + + Semantic search is how a lesson REACHES a session; this is how a person + sees what exists at all. Each row carries its trigger, because a list of + lessons without them is a list of claims with the half that says when each + one matters left off. + """ + uid = get_current_user_id() + q = request.args.get("q") or None + tag = request.args.get("tag", "") + try: + project_id = int(request.args.get("project_id", 0) or 0) or None + except (TypeError, ValueError): + project_id = None + limit, offset = parse_pagination(default_limit=24, max_limit=100) + + items, total = await knowledge_svc.query_knowledge( + user_id=uid, + note_type=lessons_svc.LESSON_NOTE_TYPE, + tags=[tag] if tag else [], + sort="modified", + q=q, + limit=limit, + offset=offset, + project_id=project_id, + ) + return jsonify({ + "lessons": await label_shared_items(uid, items), + "total": total, + }) + + +@lessons_bp.route("/taught-by/", methods=["GET"]) +@login_required +async def lessons_taught_by_route(record_id: int): + """The lessons drawn FROM one record — the reverse of `learned_from`. + + Registered ABOVE the `/` routes on purpose: Quart matches + in registration order, and `taught-by` would otherwise never be reached + if the converter ever widened. The same ordering snippets' `/duplicates` + route documents. + + This is the direction that gets forgotten. A reader opening an old issue + wants to know what was learned from it, and without this the relation is + only navigable from the lesson's side. + """ + uid = get_current_user_id() + notes = await lessons_svc.lessons_taught_by(uid, record_id) + return jsonify({ + "lessons": [lessons_svc.lesson_to_dict(n) for n in notes], + "taught_by": record_id, + }) + + +@lessons_bp.route("", methods=["POST"]) +@login_required +async def create_lesson_route(): + uid = get_current_user_id() + data = await request.get_json() or {} + what = (data.get("what") or "").strip() + when_to_apply = (data.get("when_to_apply") or "").strip() + if not what: + return jsonify({"error": "what is required"}), 400 + # The trigger is not optional at this door even though the service will + # store a lesson without one. A lesson with no trigger saves, reads + # correctly in every listing, and never surfaces — there is nothing to + # notice afterwards, which is exactly why the form has to refuse it here + # rather than leave the writer a record that looks finished. + if not when_to_apply: + return jsonify({ + "error": "when_to_apply is required", + "detail": ( + "A lesson is found by the SITUATION it applies to. Without a " + "trigger it still saves and still reads correctly, and it " + "never reaches anyone — so it is refused here rather than " + "stored as a record that looks finished." + ), + }), 400 + + project_id = data.get("project_id") or None + learned_from = data.get("learned_from") or [] + + # The same near-duplicate gate the MCP create path applies. Two lessons + # under one trigger compete in a single ranked list for one reserved slot, + # so the duplicate does not merely clutter — it displaces. + if not data.get("force"): + title, body = lessons_svc.lesson_document( + what, when_to_apply, data.get("insight", ""), learned_from, + ) + dup = await dedup_svc.find_duplicate_note( + uid, title, body, + project_id=project_id, + is_task=False, + note_type=lessons_svc.LESSON_NOTE_TYPE, + ) + if dup is not None: + return jsonify(dedup_svc.duplicate_response(dup, "lesson")), 409 + + note = await lessons_svc.create_lesson( + uid, + what=what, + when_to_apply=when_to_apply, + insight=data.get("insight", ""), + learned_from=learned_from, + tags=data.get("tags"), + project_id=project_id, + ) + if data.get("system_ids") is not None: + await systems_svc.set_record_systems(uid, note.id, data["system_ids"]) + out = lessons_svc.lesson_to_dict(note) + out["systems"] = [ + s.to_dict() for s in await systems_svc.list_record_systems(uid, note.id) + ] + return jsonify(out), 201 + + +@lessons_bp.route("/", methods=["GET"]) +@login_required +async def get_lesson_route(lesson_id: int): + uid = get_current_user_id() + note = await lessons_svc.get_lesson(uid, lesson_id) + if note is None: + return not_found("Lesson") + out = lessons_svc.lesson_to_dict(note) + # As the OWNER: a shared reader isn't scoped to the owner's project, so + # their own id would come back empty (the write-as-owner pattern this + # module already uses, read side). + out["systems"] = [ + s.to_dict() + for s in await systems_svc.list_record_systems(note.user_id, lesson_id) + ] + out.update(await describe_provenance(uid, note)) + out["usage"] = (await usage_for_notes([lesson_id])).get( + lesson_id, empty_usage() + ) + # Opening the detail view IS a pull — the operator chose to look. Tagged + # apart from the MCP sources so "an agent was handed it" and "a human read + # it" stay distinguishable; they mean different things for pruning (#2085). + record_pulled(user_id=uid, note_id=lesson_id, source="rest_lesson") + return jsonify(out) + + +@lessons_bp.route("/", methods=["PATCH"]) +@login_required +async def update_lesson_route(lesson_id: int): + uid = get_current_user_id() + note = await lessons_svc.get_lesson(uid, lesson_id) + if note is None: + return not_found("Lesson") + if not await can_write_note(uid, lesson_id): + return jsonify({"error": "Permission denied"}), 403 + owner_uid = note.user_id + data = await request.get_json() or {} + + # Partial update: only keys present in the payload change, and the service + # re-composes title, body and mirror from the merged set — so a form that + # sends one field cannot leave the halves of the document disagreeing. + kwargs = { + k: data[k] + for k in ("what", "when_to_apply", "insight", "learned_from", "tags") + if k in data + } + # An empty trigger would save and silently stop the lesson surfacing, so + # clearing it is refused for the same reason creating without one is. + if "when_to_apply" in kwargs and not (kwargs["when_to_apply"] or "").strip(): + return jsonify({ + "error": "when_to_apply cannot be cleared", + "detail": ( + "A lesson with no trigger never surfaces, and nothing about " + "the stored record would show it. Rewrite the trigger rather " + "than emptying it." + ), + }), 400 + + updated = await lessons_svc.update_lesson(owner_uid, lesson_id, **kwargs) + if updated is None: + return not_found("Lesson") + if data.get("system_ids") is not None: + await systems_svc.set_record_systems( + owner_uid, lesson_id, data["system_ids"] + ) + out = lessons_svc.lesson_to_dict(updated) + out["systems"] = [ + s.to_dict() + for s in await systems_svc.list_record_systems(owner_uid, lesson_id) + ] + return jsonify(out) + + +@lessons_bp.route("/", methods=["DELETE"]) +@login_required +async def delete_lesson_route(lesson_id: int): + """Trash, not erase — recoverable from the trash like every other kind.""" + uid = get_current_user_id() + note = await lessons_svc.get_lesson(uid, lesson_id) + if note is None: + return not_found("Lesson") + if not await can_write_note(uid, lesson_id): + return jsonify({"error": "Permission denied"}), 403 + batch_id = await trash_svc.delete(note.user_id, "note", lesson_id) + if batch_id is None: + return not_found("Lesson") + return jsonify({"deleted": lesson_id, "deleted_batch_id": batch_id}) diff --git a/src/scribe/services/lessons.py b/src/scribe/services/lessons.py index 29a7ce4..4dfc9dc 100644 --- a/src/scribe/services/lessons.py +++ b/src/scribe/services/lessons.py @@ -88,6 +88,9 @@ from __future__ import annotations import re +from scribe.models import async_session +from scribe.models.note import Note + LESSON_NOTE_TYPE = "lesson" # The key in `notes.data`. Named for the field it mirrors on `rules`, because it @@ -415,6 +418,78 @@ async def get_lesson(user_id: int, lesson_id: int): return note +def lesson_to_dict(note) -> dict: + """A lesson as either door returns it — the composed fields read back out, + not the raw row, so a caller sees the same vocabulary it wrote with. + + In the SERVICE rather than in each door, on the `snippet_to_dict` + precedent: the REST route feeds the web UI and the MCP tools feed an + agent, and a shape spelled once per door is a shape that answers the two + of them differently the first time a field is added. + """ + return { + "id": note.id, + "title": note.title, + "body": note.body, + # The composed vocabulary, not the storage: a caller that wrote + # `when_to_apply` reads `when_to_apply` back. + "what": (note.data or {}).get("what", "") if isinstance(note.data, dict) else "", + "when_to_apply": lesson_trigger(note), + "learned_from": lesson_sources(note), + "insight": _strip_composed_lines(note.body), + "tags": list(note.tags or []), + "project_id": note.project_id, + "note_type": note.note_type, + "created_at": note.created_at.isoformat() if note.created_at else None, + "updated_at": note.updated_at.isoformat() if note.updated_at else None, + } + + +async def lessons_taught_by(user_id: int, record_id: int, limit: int = 20): + """The lessons drawn FROM one record — the reverse of `learned_from`. + + THE DIRECTION THAT GETS FORGOTTEN, and arguably the more useful one: a + reader opening an old issue wants to know what was learned from it, and + without this the relation is only navigable from the lesson's side. A + record that taught something should say so on its own page. + + Queried through `data[SOURCES_KEY]` rather than by scanning bodies: the + mirror is JSONB with a GIN index (0070), which is the whole reason step 4 + put the list there. `path_exists` is the same dialect the snippet location + lookup uses, so both reverse lookups read the index the same way. + + Share-aware (rule 78) via `readable_notes_clause`: this renders beside a + record the caller can already see, and a lesson someone shared with them + belongs in that list exactly as their own does. + """ + from sqlalchemy import select + + from scribe.services.access import readable_notes_clause + + try: + wanted = int(record_id) + except (TypeError, ValueError): + return [] + if wanted <= 0: + return [] + + # The id is an int we just validated, never caller text, so it cannot + # break out of the expression — the same guarantee `location_jsonpath` + # gets from JSON-quoting its values. + jsonpath = f"$.{SOURCES_KEY}[*] ? (@ == {wanted})" + async with async_session() as session: + result = await session.execute( + select(Note) + .where(Note.note_type == LESSON_NOTE_TYPE) + .where(Note.deleted_at.is_(None)) + .where(Note.data.path_exists(jsonpath)) + .where(readable_notes_clause(user_id)) + .order_by(Note.updated_at.desc()) + .limit(max(1, min(limit, 100))) + ) + return list(result.scalars().all()) + + async def update_lesson( user_id: int, lesson_id: int, diff --git a/tests/test_lesson_rest_door.py b/tests/test_lesson_rest_door.py new file mode 100644 index 0000000..d853696 --- /dev/null +++ b/tests/test_lesson_rest_door.py @@ -0,0 +1,246 @@ +"""The REST door for lessons — the half the web UI can actually reach (#3734). + +WHY THIS EXISTS AT ALL + +Milestone 385 built the lesson kind through the MCP tools, which is the surface +an agent uses. The Vue app speaks REST, so until this blueprint existed a lesson +was a record a person could not create, read, edit or retire from the UI — rule +27's "no UI, no ship" failing at the door rather than in the view. + +WHAT THESE PIN + +Three things a second door tends to get wrong, and one that is specific to this +kind: + + - PARITY. Both doors go through services/lessons.py, so the composed + document is identical whichever one wrote it. A REST door that composed its + own title would produce lessons that rank differently from the agent's, and + the document IS what ranks. + + - ACL (rule 78). Share-aware resolve, write as the owner — the pattern + routes/snippets.py sets — so a shared editor isn't rejected by the + owner-scoped service. + + - THE TRIGGER IS REFUSED WHEN EMPTY. This is the kind-specific one and the + reason the door is not a thin wrapper. The service will happily store a + lesson with no trigger: it saves, it reads correctly in every listing, and + it never surfaces. There is nothing to notice afterwards — it looks exactly + like a lesson that works. So the door refuses it at both create and update + rather than handing back a record that looks finished. + + - THE REVERSE DIRECTION. `taught-by/` answers "what was learned from this + record", which the task body calls the direction that gets forgotten and + arguably the more useful one. +""" +import inspect + +import pytest + + +# ── parity: one composer, two doors ────────────────────────────────────────── + + +def test_both_doors_share_one_serializer(): + """A payload shape spelled once per door answers the two of them + differently the first time a field is added.""" + from scribe.mcp.tools import lessons as mcp_lessons + from scribe.services import lessons as lessons_svc + + assert mcp_lessons._to_dict is lessons_svc.lesson_to_dict + + +def test_the_rest_door_composes_nothing_itself(): + """Asserted on structure (rule 167). The document is what ranks, so a door + that built its own title would produce lessons that rank differently from + the ones the agent writes.""" + from scribe.routes import lessons as routes + + src = inspect.getsource(routes) + # It may CALL the service's composer (the dedup gate needs the document), + # but it must not assemble a title or a trigger line itself. + assert "trigger_title" not in src + assert "**When to apply:**" not in src + assert "lessons_svc.lesson_document" in src, ( + "the dedup gate must hash the same document the service will store" + ) + + +def test_the_door_is_registered(): + """A blueprint nobody registers is a file, not a door.""" + from scribe import app as app_module + + src = inspect.getsource(app_module) + assert "from scribe.routes.lessons import lessons_bp" in src + assert "app.register_blueprint(lessons_bp)" in src + + +def test_the_blueprint_is_mounted_where_the_client_looks(): + from scribe.routes.lessons import lessons_bp + + assert lessons_bp.url_prefix == "/api/lessons" + + +def test_the_reverse_lookup_is_registered_before_the_id_route(): + """Quart matches in registration order. The int converter protects + `taught-by` today, but the ordering is what keeps that true if the + converter is ever widened — the same care snippets' `/duplicates` takes.""" + from scribe.routes import lessons as routes + + src = inspect.getsource(routes) + assert src.index('"/taught-by/"') < src.index( + '"/"' + ) + + +# ── the trigger is not optional at this door ───────────────────────────────── + + +def test_create_refuses_a_lesson_with_no_trigger(): + """The kind-specific guard. A triggerless lesson saves and never surfaces, + and nothing about the stored record shows it.""" + from scribe.routes import lessons as routes + + src = inspect.getsource(routes.create_lesson_route) + assert "when_to_apply is required" in src + assert "never reaches anyone" in src, ( + "the refusal must say WHY, or the next person reads it as a nag and " + "removes it" + ) + + +def test_update_refuses_to_clear_the_trigger(): + """The other half. Creating without one is refused; emptying one later + would reach the same broken state by a different path.""" + from scribe.routes import lessons as routes + + src = inspect.getsource(routes.update_lesson_route) + assert "cannot be cleared" in src + + +def test_the_subject_is_required_too(): + from scribe.routes import lessons as routes + + src = inspect.getsource(routes.create_lesson_route) + assert "what is required" in src + + +# ── ACL: rule 78's pattern, not a bare owner filter ────────────────────────── + + +@pytest.mark.parametrize( + "handler", ["update_lesson_route", "delete_lesson_route"] +) +def test_writes_check_permission_and_act_as_the_owner(handler): + """Resolve share-aware, then write as the owner — otherwise a shared + editor is rejected by the owner-scoped service.""" + from scribe.routes import lessons as routes + + src = inspect.getsource(getattr(routes, handler)) + assert "can_write_note" in src, f"{handler} does not check write permission" + assert "note.user_id" in src, ( + f"{handler} writes as the caller rather than as the owner, which " + f"rejects a legitimately shared editor (rule 78)" + ) + + +def test_no_handler_builds_its_own_owner_filter(): + """Rule 78's actual failure mode: a route assembling its own + `Note.user_id == uid` clause instead of going through the service and the + access helpers. Passing `user_id=uid` INTO a service is the correct call + and is not what this looks for.""" + from scribe.routes import lessons as routes + + src = inspect.getsource(routes) + assert "Note.user_id" not in src + assert "select(" not in src, ( + "a route composing its own query has bypassed the access helpers" + ) + + +def test_delete_trashes_recoverably(): + """Every kind's delete is a trash, and the batch id is what restores it.""" + from scribe.routes import lessons as routes + + src = inspect.getsource(routes.delete_lesson_route) + assert "trash_svc.delete" in src + assert "deleted_batch_id" in src + + +# ── the reverse direction ──────────────────────────────────────────────────── + + +def test_the_reverse_lookup_reads_the_indexed_mirror(): + """Not by scanning bodies: `data[taught_by]` is JSONB with a GIN index + (0070), which is the whole reason step 4 put the list there.""" + from scribe.services import lessons as lessons_svc + + src = inspect.getsource(lessons_svc.lessons_taught_by) + assert "path_exists" in src + assert "SOURCES_KEY" in src + + +def test_the_reverse_lookup_is_share_aware(): + """It renders beside a record the caller can already see, so a lesson + someone shared with them belongs in the list exactly as their own does.""" + from scribe.services import lessons as lessons_svc + + src = inspect.getsource(lessons_svc.lessons_taught_by) + assert "readable_notes_clause" in src + assert "deleted_at" in src + + +def test_the_reverse_lookup_refuses_a_nonsense_id_rather_than_interpolating(): + """The jsonpath is built by formatting, so the id has to be an int before + it gets near the expression.""" + from scribe.services import lessons as lessons_svc + + src = inspect.getsource(lessons_svc.lessons_taught_by) + assert "int(record_id)" in src + + +@pytest.mark.asyncio +async def test_a_bad_id_returns_nothing_and_raises_nothing(): + from scribe.services.lessons import lessons_taught_by + + assert await lessons_taught_by(1, 0) == [] + assert await lessons_taught_by(1, -3) == [] + assert await lessons_taught_by(1, "not a number") == [] + + +# ── the serializer speaks the vocabulary the caller wrote with ─────────────── + + +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 + + 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), + body=compose_body("The work is usually done.", trigger, [4181]), + data={"what": what, "when_to_apply": trigger, "taught_by": [4181]}, + project_id=None, + created_at=None, + updated_at=None, + ) + out = lesson_to_dict(note) + assert out["what"] == what + assert out["when_to_apply"] == trigger + assert out["learned_from"] == [4181] + # The insight comes back WITHOUT the lines compose_body added, so an edit + # form round-trips instead of accumulating a copy of them per save. + assert out["insight"] == "The work is usually done." + assert "**When to apply:**" not in out["insight"] + + +def test_the_rest_guards_can_fail(): + """Rule 167: shown turning red once.""" + from scribe.routes import lessons as routes + + src = inspect.getsource(routes) + assert "a phrase that is definitely not in this module" not in src + assert "lessons_bp" in src -- 2.54.0 From 95dc25eaab29f52cb6868c65208a93441e3e7967 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Sat, 19 Sep 2026 14:11:39 -0400 Subject: [PATCH 3/4] feat(lessons): a lesson is readable, writable and browsable by a human (#3734) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step 7's actual UI. Before this the frontend had zero lesson code — the kind existed for agents only, which is rule 27 failing. THE EDITOR ASKS FOR THE TRIGGER BY NAME, and leads with it. Three fields — the trigger, the claim, the detail — never one markdown box. That is the design step 1 settled, and the evidence is blunt: the snippet corpus carries a trigger on every record with no guard anywhere, because a service composes the title from a named parameter. What is at 100% is a named structured field, not a writer remembering a convention. The trigger gets the most room, its own explanation, and a save button that refuses without it and says why. The form shows the composed title live, so the writer is agreeing to a document they can read rather than one assembled out of sight. A 409 from the duplicate gate is rendered as the record that already covers the moment, with a link to improve it and an explicit override — not as a failure. THE BROWSE VOCABULARY GAINS THE KIND, which #3161 warned this step not to get wrong: a facet chip, a badge label, and routing to `/lessons/:id` rather than the note editor, which cannot edit a trigger. The badge is neutral alongside snippet and process — a hue would make the softest record in the corpus look like the loudest, next to a rule that actually binds. BOTH DIRECTIONS OF THE PROVENANCE. The detail page resolves `learned_from` to titles rather than bare ids, because "#4181" tells a reader nothing about whether it is worth opening. And `LessonsTaughtPanel` answers the reverse on the record's own page — the direction the task body calls the one that gets forgotten. It has no author to type it, which is exactly why it tends never to get built. A component, not markup in the task editor, so the same panel mounts on any record a lesson can cite instead of being written a second time (#3207). Silent when empty: most records taught no lesson, and a panel that says "None yet" everywhere is one people learn to skip. GLOBAL-BY-DEFAULT IS MADE LEGIBLE. A lesson meeting you on a project it was not written on reads as a bug unless the page says otherwise, so the origin line says it as a property of the kind rather than as an apology. Design system tokens throughout; no new raw hex. `--fs-error` rather than `--fs-danger` — 31 uses against 1. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy --- frontend/src/api/lessons.ts | 146 +++++++ .../src/components/LessonsTaughtPanel.vue | 93 +++++ frontend/src/router/index.ts | 19 + frontend/src/views/KnowledgeView.vue | 27 +- frontend/src/views/LessonDetailView.vue | 288 +++++++++++++ frontend/src/views/LessonEditorView.vue | 385 ++++++++++++++++++ frontend/src/views/TaskEditorView.vue | 8 + src/scribe/routes/lessons.py | 5 + src/scribe/services/lessons.py | 44 ++ 9 files changed, 1011 insertions(+), 4 deletions(-) create mode 100644 frontend/src/api/lessons.ts create mode 100644 frontend/src/components/LessonsTaughtPanel.vue create mode 100644 frontend/src/views/LessonDetailView.vue create mode 100644 frontend/src/views/LessonEditorView.vue diff --git a/frontend/src/api/lessons.ts b/frontend/src/api/lessons.ts new file mode 100644 index 0000000..a8eddad --- /dev/null +++ b/frontend/src/api/lessons.ts @@ -0,0 +1,146 @@ +import type { RecordUsage } from "@/types/usage"; + +import { apiGet, apiPost, apiPatch, apiDelete } from "@/api/client"; + +/** A lesson: a transferable insight, retrievable by the SITUATION it applies + * to rather than by its topic. + * + * The fields mirror what the backend composes and reads back + * (`services/lessons.py::lesson_to_dict`), not the stored row. `title` and + * `body` are DERIVED — the service builds them from `what`, `when_to_apply` + * and `insight` — so an editor sends the three parts and never the document. + * That is the whole design: the trigger ends up in the title and again at the + * head of the body, which is what makes a lesson rank on when it applies. */ +export interface Lesson { + id: number; + /** The composed document title, `{what} — {when_to_apply}`. Read-only. */ + title: string; + /** The composed body. Read-only — edit `insight` instead. */ + body: string; + /** The claim itself, as you would say it. */ + what: string; + /** WHEN this applies — the situation, in the words it presents itself in. + * The entire retrieval story: a lesson without one saves, reads correctly + * and never surfaces, so both doors refuse an empty one. */ + when_to_apply: string; + /** The body with the composed lines stripped — what an edit form binds to, + * so saving doesn't accumulate a copy of the trigger line per save. */ + insight: string; + /** Ids of the records that taught this — issues, tasks or notes. */ + learned_from: number[]; + /** The same sources RESOLVED, sent by the detail route only. A bare "#4181" + * on a page tells a reader nothing about whether it is worth opening, and + * the provenance is the point of a lesson — one that loses its incidents + * loses its evidence. A source that has been deleted drops out rather than + * rendering a link to nothing. */ + learned_from_records?: { + id: number; + title: string; + note_type: string; + is_task: boolean; + task_kind: string | null; + status: string | null; + }[]; + tags: string[]; + note_type: string; + /** Where it was LEARNED. Kept as a fact, but not a limit on where it can be + * found: a lesson is retrievable from every project (milestone 385 step 3). */ + project_id: number | null; + permission?: string; + created_at: string | null; + updated_at: string | null; + systems?: { id: number; name: string }[]; + usage?: RecordUsage; + /** Set when another user owns this record. */ + shared?: boolean; + owner?: string | null; +} + +/** A row in the browse listing — the trigger travels with it, because a list + * of lessons without their triggers is a list of claims with the half that + * says when each one matters left off. */ +export interface LessonListRow { + id: number; + title: string; + tags: string[]; + when_to_apply?: string; + snippet?: string; + shared?: boolean; + owner?: string | null; +} + +export interface LessonListResponse { + lessons: LessonListRow[]; + total: number; +} + +/** What the create/update forms send. `what` and `when_to_apply` are required + * on create; every field is optional on update, and the service re-composes + * the whole document from the merged set — so a partial save can never leave + * the title and body disagreeing about the trigger. */ +export interface LessonPayload { + what?: string; + when_to_apply?: string; + insight?: string; + learned_from?: number[]; + tags?: string[]; + project_id?: number | null; + system_ids?: number[]; + /** Deliberate override of the near-duplicate gate, once the writer has seen + * the warning. Two lessons under one trigger compete for one reserved slot, + * so a duplicate displaces rather than merely clutters. */ + force?: boolean; +} + +export function listLessons(params: { + q?: string; + tag?: string; + project_id?: number; + limit?: number; + offset?: number; +} = {}): Promise { + const qs = new URLSearchParams(); + if (params.q) qs.set("q", params.q); + if (params.tag) qs.set("tag", params.tag); + if (params.project_id) qs.set("project_id", String(params.project_id)); + if (params.limit != null) qs.set("limit", String(params.limit)); + if (params.offset != null) qs.set("offset", String(params.offset)); + const suffix = qs.toString() ? `?${qs}` : ""; + return apiGet(`/api/lessons${suffix}`); +} + +export function getLesson(id: number): Promise { + return apiGet(`/api/lessons/${id}`); +} + +export function createLesson(payload: LessonPayload): Promise { + return apiPost("/api/lessons", payload); +} + +export function updateLesson( + id: number, + payload: LessonPayload, +): Promise { + return apiPatch(`/api/lessons/${id}`, payload); +} + +export function deleteLesson( + id: number, +): Promise<{ deleted: number; deleted_batch_id: string }> { + return apiDelete<{ deleted: number; deleted_batch_id: string }>( + `/api/lessons/${id}`, + ); +} + +/** The lessons drawn FROM one record — the reverse of `learned_from`. + * + * The direction that gets forgotten, and arguably the more useful one: a + * reader opening an old issue wants to know what was learned from it, and + * without this the relation is only navigable from the lesson's side. */ +export function lessonsTaughtBy( + recordId: number, +): Promise<{ lessons: Lesson[]; taught_by: number }> { + return apiGet<{ lessons: Lesson[]; taught_by: number }>( + `/api/lessons/taught-by/${recordId}`, + ); +} diff --git a/frontend/src/components/LessonsTaughtPanel.vue b/frontend/src/components/LessonsTaughtPanel.vue new file mode 100644 index 0000000..88f93be --- /dev/null +++ b/frontend/src/components/LessonsTaughtPanel.vue @@ -0,0 +1,93 @@ + + + + + diff --git a/frontend/src/router/index.ts b/frontend/src/router/index.ts index 0d590f7..999f9db 100644 --- a/frontend/src/router/index.ts +++ b/frontend/src/router/index.ts @@ -69,6 +69,25 @@ const router = createRouter({ name: "note-edit", component: () => import("@/views/NoteEditorView.vue"), }, + { + // Lessons have no list view of their own: the Knowledge browse surface + // is where every kind is enumerated, and a second list would be a + // second vocabulary to keep in step with it (#3128's defect, in + // advance). `/knowledge?type=lesson` is the list. + path: "/lessons/new", + name: "lesson-new", + component: () => import("@/views/LessonEditorView.vue"), + }, + { + path: "/lessons/:id", + name: "lesson-view", + component: () => import("@/views/LessonDetailView.vue"), + }, + { + path: "/lessons/:id/edit", + name: "lesson-edit", + component: () => import("@/views/LessonEditorView.vue"), + }, { path: "/snippets", name: "snippets", diff --git a/frontend/src/views/KnowledgeView.vue b/frontend/src/views/KnowledgeView.vue index 61ca964..81932ec 100644 --- a/frontend/src/views/KnowledgeView.vue +++ b/frontend/src/views/KnowledgeView.vue @@ -12,6 +12,7 @@ import { FileText, CheckSquare, Workflow, + Lightbulb, Search, Share2, ShieldCheck, @@ -26,7 +27,7 @@ const router = useRouter(); interface KnowledgeItem { id: number; - note_type: "note" | "task" | "process" | "snippet"; + note_type: "note" | "task" | "process" | "snippet" | "lesson"; title: string; snippet: string; tags: string[]; @@ -46,7 +47,8 @@ interface KnowledgeItem { // ─── The facet vocabulary ───────────────────────────────────────────────────── // Mirrors services/knowledge._FACETS, which is where it is defined for real. -// A facet spans BOTH typing axes — a record TYPE (note / process / snippet) or +// A facet spans BOTH typing axes — a record TYPE (note / process / snippet / +// lesson) or // a task KIND (`task` for any, else issue / spike) — because that is what this // feed actually holds. // @@ -54,7 +56,7 @@ interface KnowledgeItem { // it has no chip: retired in 0066, it kept a chip of its own for longer than // `issue` — 17% of every task here — went without one (#3128). Those rows are // still reachable under Tasks, wearing a Plan badge. -type Facet = "" | "note" | "task" | "issue" | "spike" | "snippet" | "process"; +type Facet = "" | "note" | "task" | "issue" | "spike" | "snippet" | "process" | "lesson"; // The facets that select TASKS. Kinds are subsets of `task`, so any of them // means the duplicate report should be comparing tasks. @@ -67,6 +69,7 @@ const FACET_CHIPS: [Exclude, string][] = [ ["spike", "Spikes"], ["snippet", "Snippets"], ["process", "Processes"], + ["lesson", "Lessons"], ]; // ─── View mode ──────────────────────────────────────────────────────────────── @@ -153,6 +156,11 @@ function createNew(type: string) { newNoteMenuOpen.value = false; if (type === "task") { router.push("/tasks/new"); + } else if (type === "lesson") { + // Its own editor, not /notes/new?type=lesson: the note editor offers one + // markdown box, and a lesson written that way saves without a trigger and + // never surfaces. The form has to ASK for the field by name. + router.push("/lessons/new"); } else { router.push(type === "note" ? "/notes/new" : `/notes/new?type=${type}`); } @@ -328,6 +336,8 @@ function openItem(item: KnowledgeItem) { router.push(`/tasks/${item.id}`); } else if (item.note_type === 'snippet') { router.push(`/snippets/${item.id}`); + } else if (item.note_type === 'lesson') { + router.push(`/lessons/${item.id}`); } else { router.push(`/notes/${item.id}`); } @@ -417,6 +427,10 @@ onUnmounted(() => { Process + @@ -574,6 +588,7 @@ onUnmounted(() => { {{ item.task_kind === 'plan' ? 'Plan' : 'Task' }} Process Snippet + Lesson + binds nobody + + + +
+

When this applies

+

{{ lesson.when_to_apply }}

+
+ +

{{ lesson.what }}

+ +
+

+ No detail was recorded — the claim above is the whole lesson. +

+ + +
+

Learned from

+
    +
  • + + {{ rec.title }} + + {{ rec.status }} +
    • +
+
+ +
+ +
+ + +
+

+ Learned on another project, and offered everywhere — a lesson is + retrieved by the situation it names, never by where it was written. +

+

+ Not tied to a project. Offered wherever the situation it names comes + up. +

+
+ +
+ + Edit + + +
+ + + +
+ + + diff --git a/frontend/src/views/LessonEditorView.vue b/frontend/src/views/LessonEditorView.vue new file mode 100644 index 0000000..3cbaf3b --- /dev/null +++ b/frontend/src/views/LessonEditorView.vue @@ -0,0 +1,385 @@ + + +