refactor(routes): one supersession seam for REST and MCP; PUT/PATCH notes share a handler; shared mask/not-found/caller helpers (#2829, milestone 296 area 5)

Reading the 28 route modules against each other and against the MCP tools:
- routes/notes.py carried a PUT and a PATCH handler that were the same
  function minus the supersedes contract on one of them — one handler now
  serves both verbs, so both carry it.
- The two _attach_supersession copies (REST + MCP) become
  supersession_svc.attach_relations(uid, note_id, data, hint=) — the seam
  the two surfaces must agree through; only the agent surface adds the
  one-sentence reading hint.
- Three local _uid() wrappers over g.user.id → scribe.auth.get_current_user_id
  like every other module; design_systems' private _not_found → routes.utils.
  not_found; the four "********" literals → settings_svc.SECRET_MASK with the
  read/write contract written once.
- routes/plugin.py: the project_id/repo resolution block and the
  comma-separated id parse were copied into three endpoints — _project_scope()
  and _int_list() now.

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

src/scribe/routes/design_systems.py

@@ -15,9 +15,10 @@ one and returns None for the other:
     those two IS the intent: distinguishing them would confirm the existence of
     records the caller may not see.
 """
-from quart import Blueprint, g, jsonify, request
+from quart import Blueprint, jsonify, request
 
-from scribe.auth import login_required
+from scribe.auth import get_current_user_id, login_required
+from scribe.routes.utils import not_found
 from scribe.services import design_systems as ds_svc
 from scribe.services.design_starter_roles import (
     DEFAULT_TOKEN_PREFIX,
@@ -28,12 +29,6 @@ from scribe.services.design_systems import DesignSystemCycle
 design_systems_bp = Blueprint("design_systems", __name__, url_prefix="/api")
 
 
-def _uid() -> int:
-    return g.user.id
-
-
-def _not_found(what: str = "design system"):
-    return jsonify({"error": f"{what} not found"}), 404
 
 
 # ── Design systems ──────────────────────────────────────────────────────
@@ -43,7 +38,7 @@ def _not_found(what: str = "design system"):
 async def list_design_systems():
     """The caller's design systems. An empty list is the ordinary state for an
     install that has never made one, not an error."""
-    rows = await ds_svc.list_design_systems(_uid())
+    rows = await ds_svc.list_design_systems(get_current_user_id())
     return jsonify({"design_systems": [s.to_dict() for s in rows]})
 
 
@@ -55,7 +50,7 @@ async def create_design_system():
     if not title:
         return jsonify({"error": "title is required"}), 400
     system = await ds_svc.create_design_system(
-        user_id=_uid(),
+        user_id=get_current_user_id(),
         title=title,
         description=data.get("description") or None,
         guidance=data.get("guidance") or None,
@@ -84,9 +79,9 @@ async def list_starter_role_groups():
 @design_systems_bp.get("/design-systems/<int:design_system_id>")
 @login_required
 async def get_design_system(design_system_id: int):
-    system = await ds_svc.get_design_system(_uid(), design_system_id)
+    system = await ds_svc.get_design_system(get_current_user_id(), design_system_id)
     if system is None:
-        return _not_found()
+        return not_found("Design system")
     return jsonify(system.to_dict())
 
 
@@ -102,19 +97,19 @@ async def update_design_system(design_system_id: int):
     if "parent_id" in data:
         fields["parent_id"] = data["parent_id"]
     try:
-        system = await ds_svc.update_design_system(_uid(), design_system_id, **fields)
+        system = await ds_svc.update_design_system(get_current_user_id(), design_system_id, **fields)
     except DesignSystemCycle as exc:
         return jsonify({"error": str(exc)}), 400
     if system is None:
-        return _not_found()
+        return not_found("Design system")
     return jsonify(system.to_dict())
 
 
 @design_systems_bp.delete("/design-systems/<int:design_system_id>")
 @login_required
 async def delete_design_system(design_system_id: int):
-    if not await ds_svc.delete_design_system(_uid(), design_system_id):
-        return _not_found()
+    if not await ds_svc.delete_design_system(get_current_user_id(), design_system_id):
+        return not_found("Design system")
     return "", 204
 
 
@@ -127,9 +122,9 @@ async def resolve_design_system(design_system_id: int):
     this returns what it ends up being. Both are real questions and answering
     only one would make the other a client-side computation.
     """
-    resolved = await ds_svc.resolve_design_system(_uid(), design_system_id)
+    resolved = await ds_svc.resolve_design_system(get_current_user_id(), design_system_id)
     if resolved is None:
-        return _not_found()
+        return not_found("Design system")
     return jsonify({
         "design_system_id": design_system_id,
         "tokens": [t.to_dict() for t in resolved],
@@ -149,9 +144,9 @@ async def get_design_system_stylesheet(design_system_id: int):
     `:root`, so the generator takes it as a parameter.
     """
     root = (request.args.get("root") or ":root").strip() or ":root"
-    result = await ds_svc.stylesheet_for_system(_uid(), design_system_id, root)
+    result = await ds_svc.stylesheet_for_system(get_current_user_id(), design_system_id, root)
     if result is None:
-        return _not_found()
+        return not_found("Design system")
     if request.args.get("format") == "css":
         return result["css"], 200, {"Content-Type": "text/css; charset=utf-8"}
     return jsonify(result)
@@ -168,10 +163,10 @@ async def check_snippets_against_system(design_system_id: int):
     """
     project_id = request.args.get("project_id", type=int) or 0
     result = await ds_svc.check_snippets_against_system(
-        _uid(), design_system_id, project_id
+        get_current_user_id(), design_system_id, project_id
     )
     if result is None:
-        return _not_found()
+        return not_found("Design system")
     return jsonify(result)
 
 
@@ -181,9 +176,9 @@ async def check_snippets_against_system(design_system_id: int):
 @login_required
 async def list_design_tokens(design_system_id: int):
     """This system's OWN tokens — its override set, not its effective set."""
-    if await ds_svc.get_design_system(_uid(), design_system_id) is None:
-        return _not_found()
-    rows = await ds_svc.list_tokens(_uid(), design_system_id)
+    if await ds_svc.get_design_system(get_current_user_id(), design_system_id) is None:
+        return not_found("Design system")
+    rows = await ds_svc.list_tokens(get_current_user_id(), design_system_id)
     return jsonify({"tokens": [t.to_dict() for t in rows]})
 
 
@@ -195,7 +190,7 @@ async def create_design_token(design_system_id: int):
     if not name:
         return jsonify({"error": "name is required"}), 400
     token = await ds_svc.create_token(
-        user_id=_uid(),
+        user_id=get_current_user_id(),
         design_system_id=design_system_id,
         name=name,
         value_by_mode=data.get("value_by_mode"),
@@ -206,7 +201,7 @@ async def create_design_token(design_system_id: int):
         order_index=data.get("order_index") or 0,
     )
     if token is None:
-        return _not_found()
+        return not_found("Design system")
     return jsonify(token.to_dict()), 201
 
 
@@ -221,17 +216,17 @@ async def update_design_token(token_id: int):
             "supersedes", "order_index",
         )
     }
-    token = await ds_svc.update_token(_uid(), token_id, **fields)
+    token = await ds_svc.update_token(get_current_user_id(), token_id, **fields)
     if token is None:
-        return _not_found("design token")
+        return not_found("Design token")
     return jsonify(token.to_dict())
 
 
 @design_systems_bp.delete("/design-tokens/<int:token_id>")
 @login_required
 async def delete_design_token(token_id: int):
-    if not await ds_svc.delete_token(_uid(), token_id):
-        return _not_found("design token")
+    if not await ds_svc.delete_token(get_current_user_id(), token_id):
+        return not_found("Design token")
     return "", 204
 
 
@@ -247,9 +242,9 @@ async def set_project_design_system(project_id: int):
     """
     data = await request.get_json() or {}
     ok = await ds_svc.set_project_design_system(
-        _uid(), project_id, data.get("design_system_id")
+        get_current_user_id(), project_id, data.get("design_system_id")
     )
     if not ok:
-        return _not_found("project or design system")
+        return not_found("Project or design system")
     return jsonify({"project_id": project_id,
                     "design_system_id": data.get("design_system_id")})