feat(moments): the moment catalog rules will mount on, readable in-session (milestone 458 step 1, #4919)

Fourteen generic moments of work (session.start, work.start … reply.ask)
plus the skill.<name> family, each with what it means and the kinds of
action that reach it, written for any kind of work rather than software
alone. The catalog is code because every install needs the same mount
points; which actions reach a moment is per-install data (step 2).

require_moment refuses an unknown name with the catalog listed, so a
typo cannot become a mount that never fires. list_moments (read-only)
and GET /api/retrieval/moments hand out the same catalog.

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

src/scribe/services/moments.py

@@ -0,0 +1,157 @@
+"""The moments of work that rules mount on (milestone 458).
+
+WHY THIS EXISTS
+
+Semantic retrieval answers "what does this text resemble?", and most rules are
+not ABOUT a topic — they belong to a MOMENT in the work. A rule about when work
+counts as finished governs the moment work is sent out, checked, closed and
+reported, and nothing said at those moments needs to resemble the rule. Matched
+on topic, it scores below every bar; mounted on its moments, it cannot miss.
+
+So a rule names the moments it belongs to, and when one happens every rule
+mounted on it arrives — by lookup, with no embedding and no score. Semantic
+retrieval stays the second net, for whatever nobody mounted.
+
+WHY THE CATALOG IS CODE, NOT DATA
+
+The moments are the product's vocabulary, not an install's. Every install needs
+the same mount points, or a rule written on one could not mean the same thing on
+another, and the plugin's hooks, the skills that declare moments and the
+instruction surfaces all name them. What varies per install is which ACTIONS
+reach a moment — one operator delivers with a push, another with a deploy
+script, a third by sending a document — and that mapping is data (step 2). The
+moment is generic; the action that reaches it is local.
+
+HOW TO WRITE ONE
+
+Domain-neutral (rule 115): Scribe's work may be software, configuration,
+infrastructure or anything else a person drives through an agent, so a
+definition names the moment in words every one of those recognises. The test
+beside this module refuses software-only vocabulary in both fields. Concrete
+actions belong in the default mappings, where they are examples of reaching a
+moment rather than the meaning of it.
+
+Names are expensive to change once rules point at them. Adding one is cheap;
+renaming one is a migration of every mount.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Moment:
+    """One point in the work that rules can mount on."""
+
+    name: str
+    """`<area>.<verb>` — the string a mount stores and a hook reports."""
+
+    means: str
+    """What is happening at this moment, in one line, for any kind of work."""
+
+    reached_by: str
+    """The kinds of action that typically reach it, said generically."""
+
+
+def _m(name: str, means: str, reached_by: str) -> tuple[str, Moment]:
+    return name, Moment(name=name, means=means, reached_by=reached_by)
+
+
+MOMENTS: dict[str, Moment] = dict([
+    _m("session.start",
+       "a working session begins, or resumes after its context was summarized",
+       "opening a session; resuming after the earlier conversation was summarized"),
+    _m("work.start",
+       "taking up a piece of work",
+       "marking a task as in progress; beginning a step of a plan"),
+    _m("work.plan",
+       "designing an approach before carrying it out",
+       "opening a plan; entering a planning mode; loading a planning procedure"),
+    _m("work.change",
+       "altering the thing being worked on",
+       "editing or creating a file; changing a setting or a document"),
+    _m("work.run",
+       "carrying out an action in the environment",
+       "running a command or a script"),
+    _m("work.verify",
+       "checking that the work does what it should",
+       "running a check; reading the result of an automated check; "
+       "loading a verification procedure"),
+    _m("work.deliver",
+       "sending work beyond the place it was made",
+       "publishing, merging, releasing, deploying or sending it to someone"),
+    _m("work.finish",
+       "declaring a piece of work done, or abandoning it",
+       "closing a task or an issue; marking it done or cancelled"),
+    _m("work.record",
+       "writing down what was learned or decided",
+       "creating a note, a lesson, a rule or a reusable example"),
+    _m("work.debug",
+       "working out why something does not behave as expected",
+       "reading a failure; loading a diagnosis procedure"),
+    _m("work.delegate",
+       "handing part of the work to another agent",
+       "dispatching a helper agent"),
+    _m("env.reach",
+       "touching a machine or a service outside the workspace",
+       "connecting to a host; calling a remote service; inspecting what runs there"),
+    _m("reply.report",
+       "reporting results to the person the work is for",
+       "the reply that ends a turn; loading a reporting procedure"),
+    _m("reply.ask",
+       "asking the person the work is for to decide or to act",
+       "a question in the reply; a structured question to the person"),
+])
+
+# A FAMILY rather than entries: one moment per named procedure, reached when it
+# is loaded. The names are the procedures' own (bundled skills, stored
+# processes), so they cannot be listed here — only their shape can.
+SKILL_PREFIX = "skill."
+SKILL_FAMILY = Moment(
+    name=f"{SKILL_PREFIX}<name>",
+    means="a named procedure is loaded",
+    reached_by="loading a skill or a stored process by its name",
+)
+_SKILL_NAME = re.compile(r"^[a-z0-9][a-z0-9_:-]*$")
+
+
+def is_moment(name: str) -> bool:
+    """Is this a name a rule can mount on — a catalog moment, or skill.<name>?"""
+    if name in MOMENTS:
+        return True
+    if name.startswith(SKILL_PREFIX):
+        return bool(_SKILL_NAME.match(name[len(SKILL_PREFIX):]))
+    return False
+
+
+def require_moment(name: str) -> str:
+    """The name, normalised, or a refusal that lists what is available.
+
+    A typo'd moment must not be mountable: the mount would be stored, read
+    back, and never fire — a rule that looks attached and is not, which is the
+    silent failure moments exist to end.
+    """
+    clean = (name or "").strip().lower()
+    if is_moment(clean):
+        return clean
+    raise ValueError(
+        f"unknown moment {name!r}. Moments are: "
+        + ", ".join(MOMENTS)
+        + f", or {SKILL_FAMILY.name} for a named procedure"
+    )
+
+
+def catalog() -> dict:
+    """The catalog as plain data, for the MCP tool and the REST door alike."""
+    return {
+        "moments": [
+            {"name": m.name, "means": m.means, "reached_by": m.reached_by}
+            for m in MOMENTS.values()
+        ],
+        "families": [
+            {"name": SKILL_FAMILY.name, "prefix": SKILL_PREFIX,
+             "means": SKILL_FAMILY.means, "reached_by": SKILL_FAMILY.reached_by},
+        ],
+        "total": len(MOMENTS),
+    }