feat(design-systems): the model, the parent chain, and the guard on it

Milestone #254 step 1 (#2286). A design system becomes a record Scribe holds
rather than prose in a rulebook: a named set of tokens with an OPTIONAL parent,
so a family system carries the house style and an app system carries only what
it changes. Answering "what does this app alter?" is then `list its tokens` —
nothing to compute.

`parent_id` is the whole model. It replaces both an `always_on` flag (a family
system is one with no parent) and a subscription join table (a project points at
ONE system; the chain supplies the rest) — less schema than the rulebook shape
it mirrors.

Two decisions the task left open, settled here:

- **Token values are JSONB keyed by mode**, not `value_light`/`value_dark`
  columns. The deciding argument was not flexibility, it was ambiguity: in a
  child system an unset mode means "inherit", in a root it means "not
  mode-dependent", and as columns both are NULL and the resolver cannot tell
  them apart. As a map, resolution is `{**parent, **child}` at every level with
  no special case for roots. Against it: queryability — but nothing filters
  tokens by value in SQL, so that buys a query no caller makes.
- **`group_name` is free text, no CHECK enum.** Groupings are each design
  system's own vocabulary; a whitelist would bake one install's kit into the
  schema. No CHECK is introduced anywhere, so rule #36 does not fire.

The cascade lives in `services/design_cascade.py` as pure functions over a
`{id: parent_id}` map, importing nothing — which is what lets both the service
and `access.py` use it without a cycle, and lets a test state a whole hierarchy
in one literal. Cycles are refused on WRITE by walking up from the proposed
parent (the cheap direction), and survived on READ by a visited-set, because a
loop from a direct DB edit must truncate rather than hang.

ACL (rule #78) is deliberately asymmetric: owning a system grants write,
reaching one through a project you can see grants READ ONLY. An editor on a
shared project must not be able to rewrite the family system every other project
in that family resolves through.

Also renames `services/design_system.py` -> `design_rulebook_import.py`. It is
the #251 prose extractor, whose role is already scheduled to become a one-shot
importer (#2288), and leaving it one character away from the new
`design_systems.py` was a trap for every later session.

Rule #115 throughout: nothing seeds a system or implies a default. An install
with zero design systems is ordinary, not degraded.

src/scribe/services/design_rulebook_import.py

@@ -0,0 +1,232 @@
+"""Design-system expectations — turning rulebook prose into checkable claims.
+
+Milestone #251 step 2. The drift panel compares what the design rulebook SAYS
+against what the stylesheet and components actually DO. This module owns the
+first half: reading a rulebook's rules and extracting the claims that can be
+mechanically checked.
+
+WHY THIS LIVES SERVER-SIDE. The frontend has no test runner — `vue-tsc --noEmit`
+is the entire check — and this is the one genuinely fiddly piece of the feature.
+Extraction happens here where pytest can assert on it; the comparison itself is
+set arithmetic and stays in the browser, where the live token values are.
+
+WHY NOT NLP. Rule statements are prose written for humans, and they should stay
+that way — they are read by people far more often than they are parsed. So this
+extracts only what is unambiguous in ANY prose: the hex colours and CSS custom
+property names a rule mentions. Everything subtler (padding scales, type ramps)
+needs a rule author to opt into a structured form, which is deliberately left for
+when someone wants it rather than invented up front.
+
+RULE #115. Nothing here assumes a design rulebook exists, or that it is this
+operator's. An install designates one; an install that hasn't gets an empty
+result and a panel that explains itself.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+
+from scribe.models.rulebook import Rule
+from scribe.services.settings import get_setting
+
+logger = logging.getLogger(__name__)
+
+# Which rulebook describes this install's design system. A plain setting rather
+# than a column: no migration, discoverable in the Settings UI (rule #25), and
+# honest about being a per-install choice rather than a property of the rulebook.
+DESIGN_RULEBOOK_SETTING = "design_rulebook_id"
+
+# `#abc` and `#aabbcc`, plus the 4/8-digit alpha forms.
+_HEX = re.compile(r"#([0-9a-fA-F]{3,8})\b")
+
+# A custom-property name as written in prose, including the slash shorthand the
+# rulebook uses: `--fs-radius-sm/md/lg/xl`, `--fs-obsidian/iron/slate/pewter`.
+_TOKEN = re.compile(r"(--[a-zA-Z][\w-]*(?:/[\w-]+)*)")
+
+# Sentence-ish split. Rules use semicolons as hard breaks as often as periods.
+_SENTENCE_SPLIT = re.compile(r"(?<=[.;])\s+|\n+")
+
+# Negation markers. Checked PER SENTENCE, which is the whole trick — see
+# _extract_from_sentence.
+_NEGATIONS = ("never", "not ", "no ", "avoid", "don't", "must not", "excluded")
+
+
+@dataclass
+class Expectation:
+    """One mechanically-checkable claim a rule makes."""
+
+    kind: str          # "token" | "color" | "prohibited_color"
+    value: str         # "--fs-obsidian" | "#14171a"
+    rule_id: int
+    rule_title: str
+    context: str       # the sentence it came from, for showing your work
+
+    def as_dict(self) -> dict:
+        return {
+            "kind": self.kind,
+            "value": self.value,
+            "rule_id": self.rule_id,
+            "rule_title": self.rule_title,
+            "context": self.context,
+        }
+
+
+@dataclass
+class ExpectationSet:
+    rulebook_id: int | None = None
+    expectations: list[Expectation] = field(default_factory=list)
+
+    def as_dict(self) -> dict:
+        return {
+            "rulebook_id": self.rulebook_id,
+            "expectations": [e.as_dict() for e in self.expectations],
+        }
+
+
+def normalize_hex(value: str) -> str | None:
+    """Fold a hex colour to a comparable form, or None if it isn't one.
+
+    Load-bearing for the whole comparison: the rulebook writes `#FFFFFF` and the
+    code writes `#fff`, and those must compare equal or the single largest drift
+    finding (#2275) reads as zero. Expands 3-digit shorthand and lowercases.
+
+    Alpha forms (4 and 8 digit) keep their alpha — `#fff` and `#ffff` are not the
+    same colour, and silently dropping the alpha would invent equality.
+    """
+    match = _HEX.fullmatch(value.strip()) or _HEX.match(value.strip())
+    if not match:
+        return None
+    digits = match.group(1).lower()
+    if len(digits) in (3, 4):
+        digits = "".join(c * 2 for c in digits)
+    if len(digits) not in (6, 8):
+        return None
+    return f"#{digits}"
+
+
+def expand_token_shorthand(raw: str) -> list[str]:
+    """`--fs-radius-sm/md/lg/xl` -> the four names it stands for.
+
+    The rulebook writes token families in a slash shorthand, and both forms it
+    uses expand correctly under one rule: take everything up to and including the
+    LAST hyphen of the first segment as the prefix, then append each alternative.
+
+        --fs-radius-sm/md/lg/xl        prefix `--fs-radius-`  -> sm, md, lg, xl
+        --fs-obsidian/iron/slate       prefix `--fs-`         -> obsidian, iron, slate
+        --fs-dur-fast/base/slow        prefix `--fs-dur-`     -> fast, base, slow
+
+    A name with no slash is returned as-is.
+    """
+    if "/" not in raw:
+        return [raw]
+    head, *rest = raw.split("/")
+    cut = head.rfind("-")
+    if cut <= 1:                      # no hyphen beyond the leading `--`
+        return [head, *rest]
+    prefix = head[: cut + 1]
+    return [head, *[f"{prefix}{part}" for part in rest if part]]
+
+
+def _is_negated(sentence: str) -> bool:
+    return any(marker in sentence.lower() for marker in _NEGATIONS)
+
+
+def _extract_from_sentence(sentence: str, rule: Rule) -> list[Expectation]:
+    """Claims in ONE sentence, with negation scoped to that sentence.
+
+    Sentence scope is what makes the prohibition detection usable. Rule 52 reads:
+
+        "Text tokens: Parchment #E8E4D8 …, Vellum #C2BFB4 …, Ash #9C9A92 ….
+         Pure white #FFFFFF is NEVER used as text color."
+
+    Three colours the palette REQUIRES and one it FORBIDS, in one statement.
+    Detecting negation across the whole statement would mark all four as
+    forbidden; detecting it per sentence gets all four right.
+    """
+    out: list[Expectation] = []
+    negated = _is_negated(sentence)
+
+    for match in _HEX.finditer(sentence):
+        value = normalize_hex(match.group(0))
+        if not value:
+            continue
+        out.append(Expectation(
+            kind="prohibited_color" if negated else "color",
+            value=value,
+            rule_id=int(rule.id),
+            rule_title=rule.title,
+            context=sentence.strip(),
+        ))
+
+    # Token names are not negated in practice — a rule says which tokens should
+    # exist, never which must not — so they are recorded as expectations
+    # regardless. If that ever changes, it needs its own kind rather than
+    # borrowing the colour one.
+    for match in _TOKEN.finditer(sentence):
+        for name in expand_token_shorthand(match.group(1)):
+            out.append(Expectation(
+                kind="token",
+                value=name,
+                rule_id=int(rule.id),
+                rule_title=rule.title,
+                context=sentence.strip(),
+            ))
+
+    return out
+
+
+def extract_expectations(rules: list[Rule]) -> list[Expectation]:
+    """Every checkable claim across a set of rules, deduped on (kind, value).
+
+    First occurrence wins so the reported rule is the one that introduced the
+    claim, which is usually the most specific place to send a reader.
+    """
+    seen: set[tuple[str, str]] = set()
+    out: list[Expectation] = []
+    for rule in rules:
+        text = " ".join(filter(None, [rule.statement or "", rule.how_to_apply or ""]))
+        for sentence in _SENTENCE_SPLIT.split(text):
+            if not sentence.strip():
+                continue
+            for expectation in _extract_from_sentence(sentence, rule):
+                key = (expectation.kind, expectation.value)
+                if key in seen:
+                    continue
+                seen.add(key)
+                out.append(expectation)
+    return out
+
+
+async def get_design_rulebook_id(user_id: int) -> int | None:
+    """The rulebook this install designated as its design system, if any."""
+    raw = (await get_setting(user_id, DESIGN_RULEBOOK_SETTING, "")).strip()
+    if not raw:
+        return None
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return None
+    return value if value > 0 else None
+
+
+async def design_expectations(user_id: int) -> ExpectationSet:
+    """Checkable claims from the designated design rulebook.
+
+    Returns an empty set when no rulebook is designated — the normal case for
+    any install but the one that set it up (rule #115). The caller shows an
+    explanatory empty state rather than treating this as an error.
+    """
+    rulebook_id = await get_design_rulebook_id(user_id)
+    if rulebook_id is None:
+        return ExpectationSet()
+
+    from scribe.services import rulebooks as rulebooks_svc
+
+    try:
+        rules = await rulebooks_svc.list_rules(user_id, rulebook_id=rulebook_id)
+    except Exception:
+        logger.warning("Design rulebook %s could not be read", rulebook_id, exc_info=True)
+        return ExpectationSet(rulebook_id=rulebook_id)
+
+    return ExpectationSet(rulebook_id=rulebook_id, expectations=extract_expectations(rules))