feat(rules): an edit leaves behind what it replaced (#3241, milestone 323 step 2)

`update_rule` now snapshots the rule's text before it writes. Rescoping rule
79 meant hand-copying the superseded statement into a task log to keep it
(#3237); the history is that, done by the write path instead of by somebody
remembering.

The snapshot is taken BEFORE the field loop, which is the one ordering that
matters. `update_rule` drops `verified_at` when `verify_with` changes, and
rewriting a check is exactly the edit whose history is worth most — a
snapshot taken afterwards would file the NEW check against the OLD wording.
Taking it up front also covers `clear`, which is a separate argument from the
field loop and is how a rule that stops being a constraint loses its check
entirely.

Session-bound rather than opening its own like note_versions.create_version:
the version and the edit that caused it commit together, so a failed update
cannot leave a history entry for an edit that never happened.

Two guards from the sibling are deliberately absent, and both are now pinned
by tests rather than only by comments — "make it consistent with
note_versions" is a plausible-sounding change that would silently start
dropping history:

- No MIN_VERSION_INTERVAL_SECONDS. That 300-second gate exists because note
  autosave fires every 60. Every version here comes from a deliberate
  update_rule, so three edits in one second are three edits.
- No MAX_VERSIONS and no pruning. A rule is edited a handful of times in its
  life; a cap could only ever discard the one edit somebody went looking for.

Kept from the sibling: the identical-content skip. Both doors resend every
field, so without it a form saved twice would file an identical snapshot.
`order_index` is excluded from the snapshot fields for the same reason —
reordering a rulebook is not an edit to what any rule says.

No delete-time snapshot, against the task's original scope and on the
operator's call. A delete goes through trash_svc and is SOFT: the rule row
keeps its full text and restores untouched, so there is nothing for a
snapshot to preserve. Anything that survived a purge would be data the
operator explicitly asked to be gone.

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

src/scribe/services/rule_versions.py

@@ -0,0 +1,82 @@
+"""A rule's edit history — the snapshot taken when an edit overwrites text.
+
+Sibling of `note_versions`, and the differences are the whole design.
+
+WHAT A VERSION IS FOR. It records what a rule USED TO SAY, because an update
+overwrites that and nothing can recompute it. It is not a record of the rule's
+lifecycle: a soft delete keeps the rule row whole and restorable, so there is
+nothing to preserve at delete time, and anything that outlived a purge would be
+data the operator explicitly asked to be gone.
+
+WHAT IS DELIBERATELY NOT COPIED FROM note_versions (milestone 323). Both of its
+guards defend against note autosave, which fires every 60 seconds and would
+otherwise burn every slot. Rules have no autosave — every version here comes
+from a deliberate `update_rule` — so both guards would only ever discard a real
+edit:
+
+- No `MIN_VERSION_INTERVAL_SECONDS`. Two deliberate edits four minutes apart
+  are two edits.
+- No `MAX_VERSIONS` and no pruning. A rule is edited a handful of times in its
+  life; a cap invites losing the one edit somebody needed.
+
+TEXT ONLY. A rule's topic, its Systems tags and its typed edges are not here.
+They have their own lifecycle, and folding them in would make one word,
+"version", mean two things — the rule's wording, and the rule's place in the
+graph.
+"""
+from sqlalchemy import select
+
+from scribe.models import async_session
+from scribe.models.rule_version import RuleVersion
+
+# The columns a version carries, and therefore the ones whose change is worth
+# a snapshot. `order_index` and `arose_from_id` are editable through
+# update_rule and are deliberately absent: reordering a rulebook is not an
+# edit to what any rule says, and a run of "moved rule 4 above rule 3"
+# snapshots would bury the edits somebody is actually looking for.
+SNAPSHOT_FIELDS = (
+    "title", "statement", "why", "how_to_apply", "when_to_apply",
+    "tier", "verify_with", "expires_when",
+)
+
+
+def snapshot(rule) -> dict:
+    """The rule's text right now, as a plain dict.
+
+    Plain values rather than the ORM object because the caller has to hold
+    this ACROSS the mutation — a live `rule` would show the new text by the
+    time it was read, which is the one thing the snapshot must not do.
+    """
+    return {f: getattr(rule, f) for f in SNAPSHOT_FIELDS}
+
+
+def record_if_changed(session, rule, actor_user_id: int | None, before: dict):
+    """Add a version holding `before`, unless the edit changed no text.
+
+    Git semantics, and not a nicety: `update_rule` is reached by callers that
+    resend every field, so without this a form saved twice would file a second
+    identical snapshot and the history would stop reading as a list of edits.
+
+    Session-BOUND, unlike `note_versions.create_version` which opens its own.
+    The version and the edit that caused it commit together or not at all;
+    a separate session could leave a snapshot behind after the update it
+    describes had failed, which is a history entry for an edit that never
+    happened.
+    """
+    if snapshot(rule) == before:
+        return None
+    version = RuleVersion(
+        rule_id=rule.id, user_id=actor_user_id, **before,
+    )
+    session.add(version)
+    return version
+
+
+async def list_versions(rule_id: int) -> list[RuleVersion]:
+    """Newest first — the reader's question is "what did this just say?"."""
+    async with async_session() as session:
+        return list((await session.execute(
+            select(RuleVersion)
+            .where(RuleVersion.rule_id == rule_id)
+            .order_by(RuleVersion.created_at.desc(), RuleVersion.id.desc())
+        )).scalars().all())

src/scribe/services/rulebooks.py

@@ -20,6 +20,7 @@ from scribe.services.verification import (
     days_since_verified as _days_since_verified,
     last_verified_label as _last_verified_label,
 )
+from scribe.services import rule_versions
 
 logger = logging.getLogger(__name__)
 
@@ -748,6 +749,10 @@ async def update_rule(
             "verify_with", "expires_when",
         }
         check_before = rule.verify_with
+        # Captured BEFORE anything is written, and as plain values — this has
+        # to survive the mutation below. A rule's history is the only record
+        # of what it used to say; the edit itself destroys that.
+        text_before = rule_versions.snapshot(rule)
         for key in clear:
             if key in allowed and key in NULLABLE_RULE_TEXT:
                 setattr(rule, key, None)
@@ -771,6 +776,11 @@ async def update_rule(
         # wrongly vouched for costs the thing the sweep exists to catch.
         if rule.verify_with != check_before:
             rule.verified_at = None
+        # Same session as the edit, so the two commit together. The snapshot
+        # holds the OLD verify_with — the check that was in force when that
+        # wording was written — which is why it is taken before the loop and
+        # not here.
+        rule_versions.record_if_changed(session, rule, user_id, text_before)
         await session.commit()
         await session.refresh(rule)
         _refresh_rule_embedding(rule)