feat(inception): projects.inception record + project_rulebook_exclusions — migration 0085 with legacy backfill; backup v10 (#2879, milestone 297 step 1)

A project's inheritance becomes a decision, not a default (milestone 297).
- projects.inception (JSONB, NULL = undecided): {decided_at, decided_by, via
  mcp|ui|legacy, choices {exclude_always_on_rulebooks, subscribe_rulebooks,
  design_system_id, seed_systems}}; on to_dict.
- project_rulebook_exclusions: a project's opt-out of a whole always-on
  rulebook — the sibling of the rule/topic suppressions, CASCADE both ways.
- services/inception.py (first cut): the vocabulary, validate_inception
  (pure, all-or-nothing), normalize_choices, is_decided. Effects come in
  step 3.
- Migration 0085 backfills every existing project via="legacy" with its
  current standing (no exclusions, its subscriptions, its design_system_id,
  no seed) so the ask fires only for projects created after this ships.
- Backup v10: rulebook_exclusions section; project rows carry inception and
  design_system_id, restored in a post-pass once rulebooks/design systems are
  mapped (design_system_id was not restored before — fixed in passing).

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

src/scribe/services/backup.py

@@ -19,6 +19,7 @@ from scribe.models.rulebook import (
     Rulebook,
     RulebookTopic,
     project_rule_suppressions,
+    project_rulebook_exclusions,
     project_rulebook_subscriptions,
     project_topic_suppressions,
 )
@@ -45,8 +46,10 @@ logger = logging.getLogger(__name__)
 # v9 (2026-08) added code_shape_uses — the ledger's consumption edges (#2870):
 # judgment-grade edges (agent/audit/import) are operator records; mechanical
 # ones (reference/hook) travel too, cheaply, and the next refresh refreshes them.
+# v10 (2026-08) added projects.inception + project_rulebook_exclusions
+# (milestone 297): the WHY a project inherits what it does, and its opt-outs.
 # Bump when the serialized schema changes.
-BACKUP_VERSION = 9
+BACKUP_VERSION = 10
 
 # Every table this backup carries, by its REAL name. Paired with _NOT_INCLUDED
 # below, these two lists must together account for the entire schema — which is
@@ -60,7 +63,7 @@ _BACKED_UP = [
     "users", "projects", "milestones", "notes", "task_logs", "note_drafts",
     "note_versions", "settings", "rulebooks", "rulebook_topics", "rules",
     "project_rulebook_subscriptions", "project_rule_suppressions",
-    "project_topic_suppressions",
+    "project_topic_suppressions", "project_rulebook_exclusions",
     # v5 (2026-08): the five-year gap this list was written to stop.
     "systems", "record_systems", "design_systems", "design_tokens",
     "note_usage_events", "repo_bindings", "note_supersessions",
@@ -112,6 +115,10 @@ def _topic_suppression_rows(rows) -> list[dict]:
     return [{"project_id": r.project_id, "topic_id": r.topic_id} for r in rows]
 
 
+def _rulebook_exclusion_rows(rows) -> list[dict]:
+    return [{"project_id": r.project_id, "rulebook_id": r.rulebook_id} for r in rows]
+
+
 # The v5 sections. Pure row-builders like the join-table helpers above, for the
 # same reason: CI has no database, so a serialiser that is a plain function is
 # one that can actually be tested.
@@ -219,6 +226,8 @@ def _project_rows(rows) -> list[dict]:
             "id": p.id, "user_id": p.user_id, "title": p.title,
             "description": p.description, "goal": p.goal, "status": p.status,
             "color": p.color,
+            "design_system_id": p.design_system_id,
+            "inception": p.inception,
             "created_at": p.created_at.isoformat(),
             "updated_at": p.updated_at.isoformat(),
         }
@@ -383,6 +392,9 @@ async def export_full_backup() -> dict:
         topic_suppressions = (await session.execute(
             select(project_topic_suppressions)
         )).all()
+        rulebook_exclusions = (await session.execute(
+            select(project_rulebook_exclusions)
+        )).all()
 
     return {
         "version": BACKUP_VERSION,
@@ -407,6 +419,7 @@ async def export_full_backup() -> dict:
         "rulebook_subscriptions": _subscription_rows(subscriptions),
         "rule_suppressions": _rule_suppression_rows(rule_suppressions),
         "topic_suppressions": _topic_suppression_rows(topic_suppressions),
+        "rulebook_exclusions": _rulebook_exclusion_rows(rulebook_exclusions),
         "systems": _system_rows(systems),
         "record_systems": _record_system_rows(record_systems),
         "design_systems": _design_system_rows(design_systems),
@@ -532,8 +545,13 @@ async def export_user_backup(user_id: int) -> dict:
                     project_topic_suppressions.c.project_id.in_(project_ids)
                 )
             )).all()
+            rulebook_exclusions = (await session.execute(
+                select(project_rulebook_exclusions).where(
+                    project_rulebook_exclusions.c.project_id.in_(project_ids)
+                )
+            )).all()
         else:
-            subscriptions = rule_suppressions = topic_suppressions = []
+            subscriptions = rule_suppressions = topic_suppressions = rulebook_exclusions = []
 
     return {
         "version": BACKUP_VERSION,
@@ -560,6 +578,7 @@ async def export_user_backup(user_id: int) -> dict:
         "rulebook_subscriptions": _subscription_rows(subscriptions),
         "rule_suppressions": _rule_suppression_rows(rule_suppressions),
         "topic_suppressions": _topic_suppression_rows(topic_suppressions),
+        "rulebook_exclusions": _rulebook_exclusion_rows(rulebook_exclusions),
         "systems": _system_rows(systems),
         "record_systems": _record_system_rows(record_systems),
         "design_systems": _design_system_rows(design_systems),
@@ -670,7 +689,7 @@ async def _restore_v2(data: dict) -> dict:
         "task_logs": 0, "note_drafts": 0, "note_versions": 0,
         "settings": 0, "rulebooks": 0, "rulebook_topics": 0, "rules": 0,
         "rulebook_subscriptions": 0, "rule_suppressions": 0,
-        "topic_suppressions": 0,
+        "topic_suppressions": 0, "rulebook_exclusions": 0,
         "systems": 0, "record_systems": 0, "design_systems": 0,
         "design_tokens": 0, "note_usage_events": 0, "repo_bindings": 0,
         "note_supersessions": 0, "code_shapes": 0, "code_shape_events": 0,
@@ -933,6 +952,17 @@ async def _restore_v2(data: dict) -> dict:
             ))
             stats["topic_suppressions"] += 1
 
+        # 14b. Always-on rulebook exclusions (v10, milestone 297)
+        for exc in data.get("rulebook_exclusions", []):
+            mapped_pid = project_id_map.get(exc.get("project_id", 0))
+            mapped_rbid = rulebook_id_map.get(exc.get("rulebook_id", 0))
+            if mapped_pid is None or mapped_rbid is None:
+                continue
+            await session.execute(project_rulebook_exclusions.insert().values(
+                project_id=mapped_pid, rulebook_id=mapped_rbid,
+            ))
+            stats["rulebook_exclusions"] += 1
+
         # --- v5 sections. Every one is data.get()-guarded, so a v2/v3/v4
         # payload restores without them rather than failing on an absent key.
 
@@ -1137,6 +1167,35 @@ async def _restore_v2(data: dict) -> dict:
             ))
             stats["code_shape_uses"] += 1
 
+        # v10: a project's design-system pointer and its inception record ride
+        # the project but point at design systems and rulebooks restored AFTER
+        # it — so they are written last, with ids re-mapped. An id that did
+        # not survive drops out of the record rather than dangling.
+        for p_data in data.get("projects", []):
+            new_pid = project_id_map.get(p_data.get("id") or 0)
+            if new_pid is None:
+                continue
+            proj = await session.get(Project, new_pid)
+            if proj is None:
+                continue
+            old_ds = p_data.get("design_system_id")
+            if old_ds:
+                proj.design_system_id = design_system_id_map.get(old_ds)
+            inception = p_data.get("inception")
+            if isinstance(inception, dict):
+                choices = dict(inception.get("choices") or {})
+                choices["exclude_always_on_rulebooks"] = [
+                    rulebook_id_map[i] for i in choices.get("exclude_always_on_rulebooks") or []
+                    if i in rulebook_id_map
+                ]
+                choices["subscribe_rulebooks"] = [
+                    rulebook_id_map[i] for i in choices.get("subscribe_rulebooks") or []
+                    if i in rulebook_id_map
+                ]
+                ds = choices.get("design_system_id")
+                choices["design_system_id"] = design_system_id_map.get(ds) if ds else None
+                proj.inception = {**inception, "choices": choices}
+
         await session.commit()
 
     logger.info("Restored v2/v3 backup: %s", stats)

src/scribe/services/inception.py

@@ -0,0 +1,84 @@
+"""Project inception — what a project was decided to inherit (milestone 297).
+
+A project's inheritance is a decision, not a default. The record lives on
+``projects.inception``::
+
+    {
+      "decided_at": "<iso>", "decided_by": <user id> | null,
+      "via": "mcp" | "ui" | "legacy",
+      "choices": {
+        "exclude_always_on_rulebooks": [rulebook ids],
+        "subscribe_rulebooks": [rulebook ids],
+        "design_system_id": <id> | null,
+        "seed_systems": bool
+      }
+    }
+
+NULL = undecided → enter_project asks. ``legacy`` is the migration's stamp on
+projects that existed before the step did (inherit-all / no design system /
+no seed), so the ask fires only for projects created after this shipped.
+
+Step 1 (this module's first cut) holds the shape and its validator; the
+effects (decide / current_defaults) arrive in step 3 and compose the
+existing services — subscriptions, exclusions, set_project_design_system,
+the Systems starter mint — and write the record LAST.
+"""
+from __future__ import annotations
+
+INCEPTION_VIAS = ("mcp", "ui", "legacy")
+CHOICE_KEYS = ("exclude_always_on_rulebooks", "subscribe_rulebooks", "design_system_id", "seed_systems")
+
+
+def _is_id_list(value) -> bool:
+    return isinstance(value, list) and all(
+        isinstance(v, int) and not isinstance(v, bool) and v > 0 for v in value
+    )
+
+
+def validate_inception(choices) -> str | None:
+    """The structural error an inception ``choices`` object would earn, or
+    None. Pure and checked BEFORE any effect is applied: a decision either
+    applies whole or errors whole (the StrictArgs lesson, #2709).
+
+    Accepts the four keys, each optional: two id lists (positive ints, no
+    duplicates between exclude and subscribe), ``design_system_id`` an int
+    or None, ``seed_systems`` a bool. Unknown keys are an error — a typo
+    must not become a silently ignored choice."""
+    if not isinstance(choices, dict):
+        return "choices must be an object"
+    unknown = sorted(set(choices) - set(CHOICE_KEYS))
+    if unknown:
+        return f"unknown inception choice(s): {', '.join(unknown)} (one of: {', '.join(CHOICE_KEYS)})"
+    excl = choices.get("exclude_always_on_rulebooks") or []
+    subs = choices.get("subscribe_rulebooks") or []
+    if not _is_id_list(excl):
+        return "exclude_always_on_rulebooks must be a list of rulebook ids"
+    if not _is_id_list(subs):
+        return "subscribe_rulebooks must be a list of rulebook ids"
+    both = sorted(set(excl) & set(subs))
+    if both:
+        return f"rulebook(s) {both} cannot be both excluded and subscribed"
+    ds = choices.get("design_system_id")
+    if ds is not None and (isinstance(ds, bool) or not isinstance(ds, int) or ds <= 0):
+        return "design_system_id must be a positive id or null"
+    seed = choices.get("seed_systems", False)
+    if not isinstance(seed, bool):
+        return "seed_systems must be true or false"
+    return None
+
+
+def normalize_choices(choices: dict | None) -> dict:
+    """The four keys, always present, in canonical form — what gets stored
+    and what the UI/agent reads back. Call after validate_inception."""
+    choices = choices or {}
+    return {
+        "exclude_always_on_rulebooks": sorted(set(choices.get("exclude_always_on_rulebooks") or [])),
+        "subscribe_rulebooks": sorted(set(choices.get("subscribe_rulebooks") or [])),
+        "design_system_id": choices.get("design_system_id"),
+        "seed_systems": bool(choices.get("seed_systems", False)),
+    }
+
+
+def is_decided(project) -> bool:
+    """A project is decided once its inception record exists (any via)."""
+    return bool(getattr(project, "inception", None))