feat(moments): rules mount on moments, through every rule door (milestone 458 step 3, #4921)

rule_moments (migration 0117) records which moments a rule arrives at, by
catalog name, cascading with the rule. rule_detail, the one seam every
rule door already returns through, gains moments beside system_ids: None
leaves the mounts alone, a list replaces them. get_rule and both
list_rules doors read them back, batched per page.

All five MCP rule/preference writes and the three REST ones take moments
and validate them before their create or update. An unknown name is
refused with the catalog listed and leaves no half-made rule behind; a
parity test pins that ordering on every door.

Backup v22 carries the mounts as a join table remapped through the rule
map; a real-Postgres round trip checks they land on the restored rule.

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

src/scribe/mcp/tools/rulebooks.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 
 from scribe.mcp._context import current_user_id
 from scribe.services import dedup as dedup_svc
+from scribe.services import moments as moments_svc
 from scribe.services import rulebooks as rulebooks_svc
 from scribe.services import trash as trash_svc
 from scribe.services.rule_usage import (
@@ -192,14 +193,16 @@ async def delete_topic(topic_id: int, confirmed: bool = False) -> dict:
 
 # ── Rule CRUD ──────────────────────────────────────────────────────────
 
-def _rule_summary(r) -> dict:
+def _rule_summary(r, moments: list[str] | None = None) -> dict:
     """The list-row shape for a rule: what an agent needs to APPLY it. The
     full record (why, how_to_apply, timestamps) is get_rule's job.
 
     One line, because the shape itself lives in the service — this was one of
     three hand-written copies that had already drifted apart (note 3026).
+    `moments` rides along only when the rule is mounted (rule_brief drops a
+    None), so an unmounted rule's row says nothing rather than "[]".
     """
-    return rulebooks_svc.rule_brief(r)
+    return rulebooks_svc.rule_brief(r, moments=moments or None)
 
 
 async def list_rules(
@@ -224,7 +227,12 @@ async def list_rules(
         topic_id=topic_id or None,
         project_id=project_id or None,
     )
-    return {"rules": [_rule_summary(r) for r in rows], "total": len(rows)}
+    # One batched read for the page, not one per row.
+    mounted = await rulebooks_svc.list_rule_moments([r.id for r in rows])
+    return {
+        "rules": [_rule_summary(r, mounted.get(r.id)) for r in rows],
+        "total": len(rows),
+    }
 
 
 async def get_rule(rule_id: int) -> dict:
@@ -311,7 +319,8 @@ async def create_rule(
     topic_id: int, title: str, statement: str, when_to_apply: str,
     why: str = "", how_to_apply: str = "", order_index: int = 0,
     arose_from_id: int = 0, verify_with: str = "", expires_when: str = "",
-    system_ids: list[int] | None = None, force: bool = False,
+    system_ids: list[int] | None = None,
+    moments: list[str] | None = None, force: bool = False,
 ) -> dict:
     """Create a new rule in a rulebook (a SHARED rule — keep it general).
 
@@ -472,6 +481,12 @@ async def create_rule(
         system_ids: Ids from list_canonical_systems — the global AREAS this
             rule is about. This is what lets a rule reach a project that is
             working in that area, so a CI rule surfaces on a CI change.
+        moments: Moments from list_moments this rule arrives at — whenever
+            one happens, the rule is delivered, whatever the words of the work
+            look like. Mount a rule here when it is about WHEN something is
+            done rather than what it is about: a rule on when work counts as
+            finished belongs at work.finish and reply.report, where nothing
+            said resembles it. Replaces the set; [] clears it.
         arose_from_id: The note or task that CAUSED this rule (an incident, a
             decision). Prefer this over naming the record inside `why`, which
             cannot be followed and does not survive a rewording.
@@ -503,6 +518,7 @@ async def create_rule(
             `overlaps` and `overlap_note` — read the top one and decide.
     """
     uid = current_user_id()
+    moments = moments_svc.require_moments(moments)
     if not force:
         dup = await dedup_svc.find_duplicate_rule(title, topic_id=topic_id)
         if dup is not None:
@@ -518,7 +534,7 @@ async def create_rule(
         why=why, how_to_apply=how_to_apply, order_index=order_index,
         verify_with=verify_with, expires_when=expires_when,
     )
-    data = await rulebooks_svc.rule_detail(uid, rule, system_ids)
+    data = await rulebooks_svc.rule_detail(uid, rule, system_ids, moments)
     data.update(dedup_svc.overlap_response(overlaps, "rule"))
     return data
 
@@ -527,7 +543,8 @@ async def create_project_rule(
     project_id: int, statement: str, when_to_apply: str, title: str = "",
     why: str = "", how_to_apply: str = "", order_index: int = 0,
     arose_from_id: int = 0, verify_with: str = "", expires_when: str = "",
-    system_ids: list[int] | None = None, force: bool = False,
+    system_ids: list[int] | None = None,
+    moments: list[str] | None = None, force: bool = False,
 ) -> dict:
     """Create a rule scoped to a single project (no rulebook needed).
 
@@ -581,6 +598,12 @@ async def create_project_rule(
             rule is about. Worth setting even on a project rule: it is what
             lets a conditional one surface when the project is working in
             that area.
+        moments: Moments from list_moments this rule arrives at — whenever
+            one happens, the rule is delivered, whatever the words of the work
+            look like. Mount a rule here when it is about WHEN something is
+            done rather than what it is about: a rule on when work counts as
+            finished belongs at work.finish and reply.report, where nothing
+            said resembles it. Replaces the set; [] clears it.
         arose_from_id: The note or task that CAUSED this rule. Reach for it
             harder here than on a rulebook rule — a project rule usually
             comes from one traceable incident in this repo, where a family
@@ -604,6 +627,7 @@ async def create_project_rule(
             `overlap_note` on the reply — see create_rule.
     """
     uid = current_user_id()
+    moments = moments_svc.require_moments(moments)
     derived_title = title.strip() or statement.strip().split(".")[0][:50]
     if not force:
         dup = await dedup_svc.find_duplicate_rule(derived_title, project_id=project_id)
@@ -619,7 +643,7 @@ async def create_project_rule(
         why=why, how_to_apply=how_to_apply, order_index=order_index,
         verify_with=verify_with, expires_when=expires_when,
     )
-    data = await rulebooks_svc.rule_detail(uid, rule, system_ids)
+    data = await rulebooks_svc.rule_detail(uid, rule, system_ids, moments)
     data.update(dedup_svc.overlap_response(overlaps, "rule"))
     return data
 
@@ -627,7 +651,8 @@ async def create_project_rule(
 async def update_rule(
     rule_id: int, title: str = "", statement: str = "", when_to_apply: str = "",
     why: str = "", how_to_apply: str = "", order_index: int = -1,
-    system_ids: list[int] | None = None, arose_from_id: int = 0,
+    system_ids: list[int] | None = None,
+    moments: list[str] | None = None, arose_from_id: int = 0,
     verify_with: str = "", expires_when: str = "", kind: str = "",
     clear_fields: list[str] | None = None,
 ) -> dict:
@@ -644,6 +669,9 @@ async def update_rule(
     milestone 394, so a rule with no trigger is not a quiet rule — it is one
     no session will ever be shown. `system_ids` REPLACES the rule's areas
     (pass [] to clear), and they decide which PROJECTS a rule binds by area.
+    `moments` REPLACES the moments it arrives at the same way — see
+    create_rule; mounting a rule whose trigger keeps missing on its moment is
+    often the better fix than rewriting the trigger.
 
     RETROFITTING A TRIGGER HAS ITS OWN TRAP, and it is not the one create_rule
     warns about. There the field is empty and the instruction is "write one".
@@ -690,6 +718,7 @@ async def update_rule(
         clear_fields: Names of fields to empty, as above.
     """
     uid = current_user_id()
+    moments = moments_svc.require_moments(moments)
     fields: dict = {}
     if title:
         fields["title"] = title
@@ -716,7 +745,7 @@ async def update_rule(
     )
     if rule is None:
         raise ValueError(f"rule {rule_id} not found")
-    return await rulebooks_svc.rule_detail(uid, rule, system_ids)
+    return await rulebooks_svc.rule_detail(uid, rule, system_ids, moments)
 
 
 # ── Preferences ─────────────────────────────────────────────────────────
@@ -737,6 +766,7 @@ async def create_preference(
     topic_id: int, title: str, statement: str, when_to_apply: str,
     arose_from_id: int, why: str = "", how_to_apply: str = "",
     order_index: int = 0, system_ids: list[int] | None = None,
+    moments: list[str] | None = None,
     force: bool = False,
 ) -> dict:
     """Record how the operator wants work done. No approval loop — write it.
@@ -806,6 +836,12 @@ async def create_preference(
             preference is about, which is what lets it reach a session working
             in that area. `update_preference` took this and create did not, so
             a preference could only be filed after the fact (#4249).
+        moments: Moments from list_moments this rule arrives at — whenever
+            one happens, the rule is delivered, whatever the words of the work
+            look like. Mount a rule here when it is about WHEN something is
+            done rather than what it is about: a rule on when work counts as
+            finished belongs at work.finish and reply.report, where nothing
+            said resembles it. Replaces the set; [] clears it.
         force: Bypass the near-duplicate gate. For a genuinely distinct
             preference, not for one that is "mostly" different — a mostly
             different preference is an update. A RULE that already answers
@@ -814,6 +850,7 @@ async def create_preference(
             the weaker copy of it and should go.
     """
     uid = current_user_id()
+    moments = moments_svc.require_moments(moments)
     if not when_to_apply.strip():
         raise ValueError(
             "when_to_apply is required: a preference with no trigger never "
@@ -839,7 +876,7 @@ async def create_preference(
         kind="preference", arose_from_id=arose_from_id,
         why=why, how_to_apply=how_to_apply, order_index=order_index,
     )
-    data = await rulebooks_svc.rule_detail(uid, rule, system_ids)
+    data = await rulebooks_svc.rule_detail(uid, rule, system_ids, moments)
     data.update(dedup_svc.overlap_response(overlaps, "preference"))
     return data
 
@@ -848,7 +885,8 @@ async def update_preference(
     rule_id: int, arose_from_id: int, statement: str = "",
     when_to_apply: str = "", title: str = "", why: str = "",
     how_to_apply: str = "", order_index: int = -1,
-    system_ids: list[int] | None = None, clear_fields: list[str] | None = None,
+    system_ids: list[int] | None = None,
+    moments: list[str] | None = None, clear_fields: list[str] | None = None,
 ) -> dict:
     """Bring a preference up to date. Doing this mid-work is expected.
 
@@ -900,9 +938,12 @@ async def update_preference(
     Args:
         rule_id: The preference to update.
         arose_from_id: What taught this change. Required; see above.
+        moments: Replaces the moments this preference arrives at (see
+            create_preference); omit to leave them alone.
         when_to_apply: The moment it applies, in session vocabulary. See above.
     """
     uid = current_user_id()
+    moments = moments_svc.require_moments(moments)
     if not arose_from_id:
         raise ValueError(
             "arose_from_id is required: this edit is the record of how the "
@@ -927,7 +968,7 @@ async def update_preference(
     )
     if rule is None:
         raise ValueError(f"rule {rule_id} not found")
-    return await rulebooks_svc.rule_detail(uid, rule, system_ids)
+    return await rulebooks_svc.rule_detail(uid, rule, system_ids, moments)
 
 
 async def rule_history(rule_id: int, version_id: int = 0) -> dict: