feat(rules): a session is told when its rules move under it (#3244, milestone 323 step 5)

The rules payload carries a marker; the write-path hook hands it back; the
server says which rules moved. Nothing is said when nothing moved.

THE COUNT IS NOT DECORATION. max(updated_at) alone cannot see a DELETED rule
— it moves no timestamp — and that is the single change that takes an
instruction OUT of force, which is the one a session most needs to hear
about. The marker is `<max updated_at>|<count>`, and a deletion is reported
through the count because there is no row left to name.

THE HOOK IS THE CARRIER because it already fires before a write, which is the
moment acting on a stale rule costs something. One comparison, no payload,
no extra round trip.

WHERE THE MARKER IS CAPTURED, and it could not be anywhere else: the
SessionStart hook, from /api/plugin/context. The model also receives one from
list_always_on_rules, but a hook cannot see an MCP tool's result — so the
value the write path compares has to be stored where a shell script can
reach it. Keyed by session id in the state dir the prior-art hook already
uses, so "changed since" means since THIS session loaded its rules.

NOT ON rules_payload, against the task's letter. Those are applicable_rules —
a different, subscription-derived set. One key name over two sets is how a
comparison starts reporting phantom changes, and the write path compares
against the always-on set.

WHAT IT CANNOT SEE is stated in both the service and the write-path arm as a
table, because a reader who finds an etag will assume it covers staleness
generally:

  another session edits a rule mid-flight             | caught
  the session is misremembering a rule read hours ago | caught
  compaction summarised the rules out of context      | NOT caught

The third is the most common, and the marker is blind to it — the etag was in
context too and went with the rules. The SessionStart nudge is that case's
only mechanism and must not be softened because this shipped. A test asserts
both modules still explain that.

Instance-agnostic (rule 115): an install with no rules produces a stable
marker rather than an error, and "no rules" reads as a state rather than as a
change. An unreadable or absent marker reports nothing — a signal that cries
wolf is worse than none, because it trains a reader to skip the line that
will one day be true. The arm fails open like every other arm on this hook.

The delivery is tested through the real build_write_path_hint rather than the
helper alone: the feature IS a line arriving in a session, and the arithmetic
being right proves nothing about that.

Live acceptance is deploy-gated and not yet recorded on the task.

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

src/scribe/services/plugin_context.py

@@ -708,6 +708,7 @@ async def build_write_path_hint(
     repo_key: str = "",
     exclude_derive: list[str] | None = None,
     exclude_rule_ids: list[int] | None = None,
+    rules_etag: str = "",
 ) -> dict:
     """Prior-art hint for the plugin's PreToolUse hook on Write/Edit.
 
@@ -1038,6 +1039,63 @@ async def build_write_path_hint(
     for arm, ids in by_arm.items():
         record_surfaced(user_id=user_id, note_ids=ids, source=arm)
 
+    # ── Have the rules moved under this session? (milestone 323) ───────
+    #
+    # THE CARRIER IS THE POINT. This hook already fires before a write — the
+    # moment acting on a stale rule actually costs something — and the check
+    # is one comparison against a marker the session already holds. No
+    # payload, no extra round trip, and nothing said when nothing moved.
+    #
+    # WHAT THIS CANNOT SEE, and a reader who finds an etag here will assume
+    # otherwise:
+    #
+    #   what goes wrong                                    | caught?
+    #   ---------------------------------------------------|--------
+    #   another session edits a rule mid-flight             | yes
+    #   the session is misremembering a rule read hours ago | yes
+    #   compaction summarised the rules out of context      | NO
+    #
+    # The third is the most common and this is blind to it: the etag was in
+    # context too and went with the rules. The SessionStart nudge is that
+    # case's only mechanism and must not be softened because this shipped.
+    #
+    # Fails open, like every other arm here: a staleness hint must never
+    # break a write.
+    if rules_etag:
+        try:
+            current = await rulebooks_svc.list_always_on_rules(
+                user_id, project_id=project_id or 0,
+            )
+            if rulebooks_svc.rules_etag(current) != rules_etag:
+                moved = rulebooks_svc.rules_moved_since(current, rules_etag)
+                held = rulebooks_svc.etag_count(rules_etag)
+                bits = []
+                if moved:
+                    named = ", ".join(
+                        f"#{r.id} \u201c{r.title}\u201d" for r in moved[:3]
+                    )
+                    more = len(moved) - 3
+                    bits.append(
+                        f"{named}" + (f", and {more} more" if more > 0 else "")
+                    )
+                # A DELETED rule moves no timestamp and leaves no row to name,
+                # so the count is the only thing that can report the one change
+                # that takes an instruction OUT of force.
+                if held is not None and held != len(current):
+                    delta = len(current) - held
+                    bits.append(
+                        f"{abs(delta)} rule(s) {'added' if delta > 0 else 'no longer in force'}"
+                    )
+                if bits:
+                    lines.append(
+                        "Your loaded rules have changed since this session "
+                        "started — " + "; ".join(bits) + ". Re-read them with "
+                        "list_always_on_rules() before relying on the set you "
+                        "are holding."
+                    )
+        except Exception:
+            logger.debug("write-path rules-etag arm failed", exc_info=True)
+
     # ── Standing rules that may apply here (milestone 307) ──────────────
     #
     # A SUGGESTION, not a binding surface, and the distinction is the design
@@ -1208,7 +1266,10 @@ async def build_session_context(
             its normalized key — triggers a one-line "bind this repo" hint so
             the binding is self-healing.
 
-    Returns {"context": str, "rule_count": int, "project": dict | None}.
+    Returns {"context": str, "rule_count": int, "project": dict | None,
+    "rules_etag": str}. The etag is for the HOOK, not for the model — the
+    hook stores it and hands it back on each write so the server can say
+    whether these rules have moved since the session loaded them.
     `context` is markdown ready to drop into `additionalContext`; it is capped
     at _MAX_CHARS with an explicit truncation note so the hook can pass it
     through verbatim.
@@ -1317,4 +1378,12 @@ async def build_session_context(
     if len(context) > _MAX_CHARS:
         context = context[:_MAX_CHARS].rstrip() + "\n\n…(truncated — call list_always_on_rules())"
 
-    return {"context": context, "rule_count": len(rules), "project": project_dict}
+    return {
+        "context": context,
+        "rule_count": len(rules),
+        "project": project_dict,
+        # Computed from the rules THIS payload was built from, not re-queried:
+        # the marker has to describe the set the session is actually holding,
+        # and a second query could disagree with the first.
+        "rules_etag": rulebooks_svc.rules_etag(rules),
+    }