Merge pull request 'Ledger follow-ups from the shape audit (milestone 294: #2868–#2874)' (#122 ) from dev into main

feat(backup): code_shape_uses travels (v9); consumer-map test expects uses (#2870 )
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-21 15:24:03 -04:00 · 2026-08-21 15:21:13 -04:00 · 2026-08-21 15:18:25 -04:00 · 2026-08-21 15:15:32 -04:00 · 2026-08-21 15:15:09 -04:00 · 2026-08-21 15:14:34 -04:00
154 changed files with 2888 additions and 3106 deletions
@@ -0,0 +1,26 @@
+"""Per-binding ref — the branch a project's ledger follows (#2873, milestone 294)
+
+Revision ID: 0082
+Revises: 0081
+Create Date: 2026-08-21
+
+A repo binding used to imply the repo's default branch; the shape ledger
+therefore only saw work after a merge to main, while the operator's work
+lands on dev (rule 1). `ref` names the branch the coverage refresh reads —
+NULL keeps today's behaviour (the forge's default branch).
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0082"
+down_revision = "0081"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("repo_bindings", sa.Column("ref", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("repo_bindings", "ref")
@@ -0,0 +1,26 @@
+"""Exempt/variant reason codes — a small fixed catalogue beside the prose (#2874, milestone 294)
+
+Revision ID: 0083
+Revises: 0082
+Create Date: 2026-08-21
+
+The 2026-08 audit wrote the same free-text reason thousands of times
+("scoped rule — styles one element of this view"); a judgment's WHY stays
+prose, but an optional code from a fixed catalogue makes the ledger
+filterable and aggregable ("how many pure helpers, how many test helpers").
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0083"
+down_revision = "0082"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("code_shapes", sa.Column("reason_code", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("code_shapes", "reason_code")
@@ -0,0 +1,40 @@
+"""code_shape_uses — consumption edges, separate from conformance (#2870, milestone 294)
+
+Revision ID: 0084
+Revises: 0083
+Create Date: 2026-08-21
+
+A ledger row carries ONE snippet_id: what shape this is (instance/variant of
+a canon). But a shape can also CALL several canonical helpers — a service
+function that is an instance of the service-function convention and a
+consumer of hash_token. The 2026-08 audit had to pick one; hook evidence
+("pulled #N then wrote code referencing it") was stamped as instance when it
+is a uses fact. This table holds the many-valued relation: shape → snippet,
+with the basis and the evidence. Cascades with the shape and the snippet.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0084"
+down_revision = "0083"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "code_shape_uses",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("shape_id", sa.Integer(), sa.ForeignKey("code_shapes.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("snippet_id", sa.Integer(), sa.ForeignKey("notes.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("basis", sa.Text(), nullable=False),
+        sa.Column("evidence", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.UniqueConstraint("shape_id", "snippet_id", name="uq_code_shape_uses_shape_snippet"),
+    )
+    op.create_index("ix_code_shape_uses_snippet", "code_shape_uses", ["snippet_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_code_shape_uses_snippet", table_name="code_shape_uses")
+    op.drop_table("code_shape_uses")
@@ -38,6 +38,20 @@ async function handleResponse<T>(res: Response, path: string): Promise<T> {
  return res.json() as Promise<T>;
 }

+/**
+ * The server's `{"error": "..."}` message from a failed call, or `fallback`
+ * when the failure carried none (network error, non-JSON body). The one place
+ * the error envelope is unpacked on the client — views used to restate this
+ * as a six-line `"body" in e` branch at every catch site.
+ */
+export function apiErrorMessage(e: unknown, fallback: string): string {
+  if (e && typeof e === "object" && "body" in e) {
+    const body = (e as { body?: { error?: unknown } }).body;
+    if (body && typeof body.error === "string" && body.error) return body.error;
+  }
+  return fallback;
+}
+
 export async function apiGet<T>(path: string): Promise<T> {
  const res = await fetch(path);
  return handleResponse<T>(res, path);
@@ -0,0 +1,115 @@
+/* ── Auth surface (Login / Register / RegisterInvite / ForgotPassword / ResetPassword) ──
+   The five auth views used to carry byte-identical copies of these rules in
+   their scoped blocks (2026-08 shape audit). Loaded per view with
+   <style src="@/assets/auth-shared.css" />, like editor-shared.css; the form
+   rules are scoped under .auth-card so nothing leaks into the app's other
+   .field/.input usages. Per-view one-offs (Login's .divider/.forgot-link)
+   stay in the view. */
+.auth-page {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100vh;
+  padding: 1rem;
+}
+.auth-card {
+  width: 100%;
+  max-width: 400px;
+  background: var(--fs-surface-raised);
+  border: 1px solid var(--fs-border-color);
+  border-radius: var(--fs-radius-lg);
+  padding: 2rem;
+}
+.auth-brand {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  margin-bottom: 1.5rem;
+}
+.auth-card h1 {
+  margin: 0;
+  text-align: center;
+}
+.auth-hint {
+  text-align: center;
+  font-size: 0.9rem;
+  color: var(--fs-text-secondary);
+  margin-bottom: 1rem;
+}
+.auth-hint a {
+  color: var(--fs-accent);
+}
+/* A centred status paragraph block: registration closed, invalid/expired
+   token, "check your inbox". One rule — the views used to name it
+   .closed-msg / .error-block / .success-msg with identical bodies. */
+.auth-note {
+  text-align: center;
+  color: var(--fs-text-secondary);
+  font-size: 0.95rem;
+  padding: 0.5rem 0;
+}
+.auth-note p {
+  margin: 0.5rem 0;
+}
+.auth-loading {
+  text-align: center;
+  color: var(--fs-text-tertiary);
+  font-size: 0.95rem;
+  padding: 1rem 0;
+}
+.auth-card .field {
+  margin-bottom: 1rem;
+}
+.auth-card .field label {
+  display: block;
+  font-size: 0.9rem;
+  font-weight: 600;
+  margin-bottom: 0.35rem;
+}
+.auth-card .input {
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--fs-border-color);
+  border-radius: var(--fs-radius-sm);
+  font-size: 0.95rem;
+  background: var(--fs-surface-page);
+  color: var(--fs-text-primary);
+  box-sizing: border-box;
+}
+.auth-card .input:focus {
+  outline: none;
+  border-color: var(--fs-accent);
+}
+.auth-card .input:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+.auth-card .input-error,
+.auth-card .input-error:focus {
+  border-color: var(--fs-error);
+}
+.auth-card .field-hint {
+  margin: 0.35rem 0 0;
+  font-size: 0.8rem;
+  color: var(--fs-text-tertiary);
+}
+.auth-card .error-hint {
+  margin: 0.35rem 0 0;
+  font-size: 0.8rem;
+  color: var(--fs-error);
+}
+.auth-card .error-msg {
+  color: var(--fs-error);
+  font-size: 0.9rem;
+  margin: 0 0 0.75rem;
+}
+.auth-footer {
+  text-align: center;
+  font-size: 0.9rem;
+  color: var(--fs-text-secondary);
+  margin: 1rem 0 0;
+}
+.auth-footer a {
+  color: var(--fs-accent);
+}
@@ -221,3 +221,79 @@
                                                     is the page's main action */
  font-size: var(--fs-size-body-sm);
 }
+
+
+/* ── Modal ─────────────────────────────────────────────────────────────────
+   The one overlay/card/button shape for every in-app dialog (ConfirmDialog,
+   the create-project / merge-snippet / systems dialogs, the editors' confirm
+   prompts). Global on purpose: ConfirmDialog teleports to <body> and has no
+   styles of its own, so these must be loaded with the app, not with whichever
+   view happens to be open. Views add only their own overrides (a wider card,
+   a form layout). Destructive = action-destructive per the Hybrid rule. */
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: var(--fs-overlay);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 200;
+}
+.modal-card {
+  background: var(--fs-surface-raised);
+  border: 1px solid var(--fs-border-color);
+  border-radius: var(--fs-radius-lg);
+  padding: 1.5rem;
+  width: 100%;
+  max-width: 400px;
+  box-shadow: 0 8px 32px var(--color-shadow);
+}
+.modal-title {
+  margin: 0 0 0.75rem;
+  font-size: 1.05rem;
+}
+.modal-message {
+  font-size: 0.9rem;
+  color: var(--fs-text-secondary);
+  margin: 0 0 1.25rem;
+  line-height: 1.5;
+}
+.modal-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.5rem;
+}
+.modal-btn {
+  padding: 0.4rem 0.9rem;
+  border: 1px solid var(--fs-border-color);
+  background: var(--fs-surface-raised);
+  color: var(--fs-text-primary);
+  border-radius: var(--fs-radius-sm);
+  cursor: pointer;
+  font-size: 0.875rem;
+  font-family: inherit;
+}
+.modal-btn:hover {
+  background: var(--fs-surface-page);
+}
+.modal-btn-primary {
+  background: var(--fs-action-primary);
+  border-color: var(--fs-action-primary);
+  color: var(--fs-text-on-action);
+}
+.modal-btn-primary:hover:not(:disabled) {
+  background: var(--fs-action-primary-hover);
+}
+.modal-btn-primary:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+.modal-btn-danger {
+  background: var(--fs-action-destructive);
+  border-color: var(--fs-action-destructive);
+  color: var(--fs-text-on-action);
+}
+.modal-btn-danger:hover {
+  background: var(--fs-action-destructive-hover);
+  border-color: var(--fs-action-destructive-hover);
+}
@@ -316,53 +316,6 @@
  gap: 0.5rem;
 }

-/* ── Modal ── */
-.modal-overlay {
-  position: fixed;
-  inset: 0;
-  background: var(--fs-overlay);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  z-index: 200;
-}
-.modal-card {
-  background: var(--fs-surface-raised);
-  border-radius: var(--fs-radius-lg);
-  padding: 1.5rem;
-  max-width: 400px;
-  width: 90%;
-  box-shadow: 0 8px 32px var(--color-shadow);
-}
-.modal-title {
-  margin: 0 0 0.5rem;
-  font-size: 1.1rem;
-}
-.modal-message {
-  margin: 0 0 1.25rem;
-  color: var(--fs-text-secondary);
-  font-size: 0.95rem;
-}
-.modal-actions {
-  display: flex;
-  gap: 0.5rem;
-  justify-content: flex-end;
-}
-.modal-btn {
-  padding: 0.45rem 1rem;
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-sm);
-  background: var(--fs-surface-raised);
-  color: var(--fs-text-primary);
-  cursor: pointer;
-  font-size: 0.9rem;
-}
-.modal-btn-danger {
-  background: var(--fs-error);
-  color: var(--fs-text-on-action);
-  border-color: var(--fs-error);
-}
-
 /* ── Floating inline assist button (teleported to body) ── */
 .inline-assist-btn {
  position: fixed;
@@ -3,6 +3,7 @@ import { ref, computed, onMounted } from "vue";
 import { apiGet, pinNoteVersion, unpinNoteVersion } from "@/api/client";
 import DiffView from "@/components/DiffView.vue";
 import type { DiffLine } from "@/composables/useAssist";
+import { fmtStamp } from "@/utils/dateFormat";

 interface NoteVersion {
  id: number;
@@ -56,14 +57,6 @@ const diff = computed<DiffLine[]>(() => {
  return result;
 });

-function formatDate(iso: string): string {
-  const d = new Date(iso);
-  return d.toLocaleString(undefined, {
-    month: 'short', day: 'numeric', year: 'numeric',
-    hour: '2-digit', minute: '2-digit',
-  });
-}
-
 async function loadVersions() {
  loading.value = true;
  try {
@@ -212,7 +205,7 @@ onMounted(loadVersions);
                v-if="v.pin_kind === 'manual' && v.pin_label"
                class="history-item-label"
              >{{ v.pin_label }}</div>
-              <div class="history-item-date">{{ formatDate(v.created_at) }}</div>
+              <div class="history-item-date">{{ fmtStamp(v.created_at) }}</div>
            </div>
          </div>

@@ -515,36 +515,4 @@ async function confirmDelete() {
 }
 .skel-row--short { width: 65%; }

-/* ── Modal ────────────────────────────────────────────────────── */
-.modal-overlay {
-  position: fixed; inset: 0;
-  background: var(--fs-overlay);
-  display: flex; align-items: center; justify-content: center;
-  z-index: 200;
-}
-.modal-card {
-  background: var(--fs-surface-raised);
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-lg);
-  padding: 1.5rem;
-  width: 100%;
-  max-width: 400px;
-  box-shadow: 0 8px 32px var(--color-shadow);
-}
-.modal-title { margin: 0 0 0.75rem; font-size: 1.05rem; }
-.modal-message { font-size: 0.9rem; color: var(--fs-text-secondary); margin: 0 0 1.25rem; line-height: 1.5; }
-.modal-actions { display: flex; justify-content: flex-end; gap: 0.5rem; }
-.modal-btn {
-  padding: 0.4rem 0.9rem;
-  border: 1px solid var(--fs-border-color);
-  background: var(--fs-surface-raised);
-  color: var(--fs-text-primary);
-  border-radius: var(--fs-radius-sm);
-  cursor: pointer;
-  font-size: 0.875rem;
-  font-family: inherit;
-}
-.modal-btn:hover { background: var(--fs-surface-page); }
-.modal-btn-danger { background: var(--fs-action-destructive); border-color: var(--fs-action-destructive); color: var(--fs-text-on-action); }
-.modal-btn-danger:hover { background: var(--fs-action-destructive-hover); border-color: var(--fs-action-destructive-hover); }
 </style>
@@ -3,6 +3,7 @@ import { ref, onMounted } from "vue";
 import { apiGet, apiPost, apiPatch, apiDelete } from "@/api/client";
 import { renderMarkdown } from "@/utils/markdown";
 import type { TaskLog } from "@/types/task";
+import { fmtStamp } from "@/utils/dateFormat";

 const props = defineProps<{ taskId: number }>();

@@ -15,13 +16,6 @@ const editingId = ref<number | null>(null);
 const editContent = ref("");
 const editDuration = ref("");

-function formatDate(iso: string): string {
-  const d = new Date(iso);
-  const datePart = d.toLocaleDateString(undefined, { month: "short", day: "numeric", year: "numeric" });
-  const timePart = d.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
-  return `${datePart}, ${timePart}`;
-}
-
 function formatDuration(minutes: number): string {
  if (minutes < 60) return `${minutes} min`;
  const h = Math.floor(minutes / 60);
@@ -128,7 +122,7 @@ onMounted(loadLogs);
      </template>
      <template v-else>
        <div class="log-entry-meta">
-          <span class="log-date">{{ formatDate(log.created_at) }}</span>
+          <span class="log-date">{{ fmtStamp(log.created_at) }}</span>
          <span v-if="log.duration_minutes" class="log-duration-badge">
            {{ formatDuration(log.duration_minutes) }}
          </span>
@@ -11,6 +11,7 @@ import TagInput from "@/components/TagInput.vue";
 import MarkdownToolbar from "@/components/MarkdownToolbar.vue";
 import WordCount from "@/components/WordCount.vue";
 import { Trash2, X } from "lucide-vue-next";
+import { relativeTimeOrDate } from "@/composables/useRelativeTime";

 const props = defineProps<{
  projectId: number;
@@ -252,20 +253,6 @@ async function confirmDelete(id: number) {
  }
 }

-function formatDate(iso: string): string {
-  const d = new Date(iso);
-  const now = new Date();
-  const diffMs = now.getTime() - d.getTime();
-  const diffMin = Math.floor(diffMs / 60_000);
-  const diffHrs = Math.floor(diffMs / 3_600_000);
-  const diffDays = Math.floor(diffMs / 86_400_000);
-  if (diffMin < 1) return "just now";
-  if (diffMin < 60) return `${diffMin}m ago`;
-  if (diffHrs < 24) return `${diffHrs}h ago`;
-  if (diffDays < 7) return `${diffDays}d ago`;
-  return d.toLocaleDateString(undefined, { month: "short", day: "numeric" });
-}
-
 watch(noteTitle, () => { dirty.value = true; });
 watch(noteBody, () => { dirty.value = true; if (editingId.value) scheduleLinkCheck(); });
 watch(noteTags, () => { dirty.value = true; });
@@ -346,7 +333,7 @@ defineExpose({ reload: loadProjectNotes });
        >
          <div class="note-row-main">
            <span class="note-row-title">{{ note.title || 'Untitled' }}</span>
-            <span class="note-row-age">{{ formatDate(note.updated_at) }}</span>
+            <span class="note-row-age">{{ relativeTimeOrDate(note.updated_at) }}</span>
          </div>
          <div v-if="note.tags?.length" class="note-row-tags">
            <span
@@ -6,6 +6,7 @@ import { useToastStore } from "@/stores/toast";
 import TaskLogSection from "@/components/TaskLogSection.vue";
 import { renderMarkdown } from "@/utils/markdown";
 import { Trash2, X } from "lucide-vue-next";
+import { relativeTimeOrDate } from "@/composables/useRelativeTime";

 const props = defineProps<{ projectId: number }>();

@@ -198,20 +199,6 @@ function cancelDeleteTask() {
  deleteConfirmPending.value = false;
 }

-function formatDate(iso: string): string {
-  const d = new Date(iso);
-  const now = new Date();
-  const diffMs = now.getTime() - d.getTime();
-  const diffMin = Math.floor(diffMs / 60_000);
-  const diffHrs = Math.floor(diffMs / 3_600_000);
-  const diffDays = Math.floor(diffMs / 86_400_000);
-  if (diffMin < 1) return "just now";
-  if (diffMin < 60) return `${diffMin}m ago`;
-  if (diffHrs < 24) return `${diffHrs}h ago`;
-  if (diffDays < 7) return `${diffDays}d ago`;
-  return d.toLocaleDateString(undefined, { month: "short", day: "numeric" });
-}
-
 onMounted(loadAll);
 defineExpose({ reload: loadAll });
 </script>
@@ -256,7 +243,7 @@ defineExpose({ reload: loadAll });
              <span v-if="task.priority && task.priority !== 'none'" :class="['priority-dot', PRIORITY_CLASS[task.priority] ?? '']"></span>
              <span class="task-title" :class="{ done: task.status === 'done' }">{{ task.title }}</span>
              <span v-if="task.due_date" :class="['task-due', { overdue: isRowOverdue(task) }]">{{ task.due_date }}</span>
-              <span class="task-age">{{ formatDate(task.updated_at) }}</span>
+              <span class="task-age">{{ relativeTimeOrDate(task.updated_at) }}</span>
            </li>
            <li v-if="groupedTasks.noMilestone.length === 0" class="empty-group">No tasks</li>
          </ul>
@@ -281,7 +268,7 @@ defineExpose({ reload: loadAll });
              <span v-if="task.priority && task.priority !== 'none'" :class="['priority-dot', PRIORITY_CLASS[task.priority] ?? '']"></span>
              <span class="task-title" :class="{ done: task.status === 'done' }">{{ task.title }}</span>
              <span v-if="task.due_date" :class="['task-due', { overdue: isRowOverdue(task) }]">{{ task.due_date }}</span>
-              <span class="task-age">{{ formatDate(task.updated_at) }}</span>
+              <span class="task-age">{{ relativeTimeOrDate(task.updated_at) }}</span>
            </li>
            <li v-if="msTasks.length === 0" class="empty-group">No tasks</li>
          </ul>
@@ -9,3 +9,15 @@ export function relativeTime(iso: string): string {
  const days = Math.floor(hours / 24);
  return `${days}d ago`;
 }
+
+/**
+ * relativeTime() for the recent past, a short date once it's a week old —
+ * the workspace panels' list-row timestamp ("3h ago" / "Jan 15"). Two
+ * panels used to carry identical copies of this.
+ */
+export function relativeTimeOrDate(iso: string): string {
+  const d = new Date(iso);
+  const days = Math.floor((Date.now() - d.getTime()) / 86_400_000);
+  if (days < 7) return relativeTime(iso);
+  return d.toLocaleDateString(undefined, { month: "short", day: "numeric" });
+}
@@ -1,65 +1,32 @@
-/** Shared date/time formatting helpers used across Calendar, Home, Knowledge, etc. */
-
-function _isSameDay(a: Date, b: Date): boolean {
-  return a.getFullYear() === b.getFullYear() &&
-    a.getMonth() === b.getMonth() &&
-    a.getDate() === b.getDate()
-}
-
-/** "9:30 AM" */
-export function fmtTime(dt: string): string {
-  return new Date(dt).toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" })
-}
-
-/** "Mon, Jan 15" or "Mon, Jan 15, 9:30 AM" */
-export function fmtDateTime(dt: string, allDay: boolean): string {
-  const d = new Date(dt)
-  const datePart = d.toLocaleDateString(undefined, { weekday: "short", month: "short", day: "numeric" })
-  if (allDay) return datePart
-  return `${datePart}, ${d.toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" })}`
-}
-
 /**
- * "Today 9:30 AM" / "Tomorrow 9:30 AM" / "Mon, Jan 15 9:30 AM"
- * For all-day events returns "Today" / "Tomorrow" / "Mon, Jan 15"
+ * Shared date/time formatting — one rule per display shape. Views import
+ * these instead of carrying a local formatDate(): the 2026-08 shape audit
+ * found eight copies across views/components, three of them byte-identical.
+ * (The previous Calendar/Home helpers in this file had no callers left and
+ * were removed in the same pass.)
+ *
+ * Relative forms ("5m ago") live next door in composables/useRelativeTime.
 */
-export function fmtRelativeDateTime(dt: string, allDay: boolean): string {
-  try {
-    const d = new Date(dt)
-    const now = new Date()
-    const tomorrow = new Date(now)
-    tomorrow.setDate(now.getDate() + 1)

-    const timeStr = allDay ? "" : ` ${d.toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" })}`
-
-    if (_isSameDay(d, now)) return `Today${timeStr}`
-    if (_isSameDay(d, tomorrow)) return `Tomorrow${timeStr}`
-    return d.toLocaleDateString(undefined, { weekday: "short", month: "short", day: "numeric" }) + timeStr
-  } catch {
-    return dt
-  }
+/** "Jan 15, 2026" — a date with no time of day (user created_at, key expiry). */
+export function fmtDate(iso: string): string {
+  return new Date(iso).toLocaleDateString(undefined, {
+    year: "numeric", month: "short", day: "numeric",
+  });
 }

-/**
- * Label-only: "Today" / "Tomorrow" / "Mon, Jan 15"
- */
-export function fmtDayLabel(dt: string): string {
-  try {
-    const d = new Date(dt)
-    const now = new Date()
-    const tomorrow = new Date(now)
-    tomorrow.setDate(now.getDate() + 1)
-    if (_isSameDay(d, now)) return "Today"
-    if (_isSameDay(d, tomorrow)) return "Tomorrow"
-    return d.toLocaleDateString(undefined, { weekday: "short", month: "short", day: "numeric" })
-  } catch {
-    return dt
-  }
+/** "Jan 15, 2026, 09:30 AM" — a full timestamp (task logs, version history). */
+export function fmtStamp(iso: string): string {
+  return new Date(iso).toLocaleString(undefined, {
+    month: "short", day: "numeric", year: "numeric",
+    hour: "2-digit", minute: "2-digit",
+  });
 }

-/** "Jan 15" or "Jan 15, 9:30 AM" — compact, no weekday */
-export function fmtCompact(dt: string, allDay: boolean): string {
-  const d = new Date(dt)
-  if (allDay) return d.toLocaleDateString(undefined, { month: "short", day: "numeric" })
-  return d.toLocaleString(undefined, { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" })
+/** "Jan 15, 09:30:05 AM" — log-table timestamp: seconds matter, the year doesn't. */
+export function fmtLogStamp(iso: string): string {
+  return new Date(iso).toLocaleString(undefined, {
+    month: "short", day: "numeric",
+    hour: "2-digit", minute: "2-digit", second: "2-digit",
+  });
 }
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { ref } from "vue";
-import { apiPost } from "@/api/client";
+import { apiPost, apiErrorMessage } from "@/api/client";
 import AppLogo from "@/components/AppLogo.vue";

 const email = ref("");
@@ -15,12 +15,7 @@ async function handleSubmit() {
    await apiPost("/api/auth/forgot-password", { email: email.value });
    submitted.value = true;
  } catch (e: unknown) {
-    if (e && typeof e === "object" && "body" in e) {
-      const body = (e as { body?: { error?: string } }).body;
-      error.value = body?.error || "Something went wrong";
-    } else {
-      error.value = "Something went wrong";
-    }
+    error.value = apiErrorMessage(e, "Something went wrong");
  } finally {
    submitting.value = false;
  }
@@ -55,7 +50,7 @@ async function handleSubmit() {
        </form>
      </template>

-      <div v-else class="success-msg">
+      <div v-else class="auth-note">
        <p>If an account exists with that email address, you will receive a password reset link shortly.</p>
        <p>Check your email and follow the instructions to reset your password.</p>
      </div>
@@ -67,83 +62,4 @@ async function handleSubmit() {
  </main>
 </template>

-<style scoped>
-.auth-page {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  min-height: 100vh;
-  padding: 1rem;
-}
-.auth-card {
-  width: 100%;
-  max-width: 400px;
-  background: var(--fs-surface-raised);
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-lg);
-  padding: 2rem;
-}
-.auth-brand {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  gap: 0.5rem;
-  margin-bottom: 1.5rem;
-}
-.auth-card h1 {
-  margin: 0;
-  text-align: center;
-}
-.auth-hint {
-  text-align: center;
-  font-size: 0.9rem;
-  color: var(--fs-text-secondary);
-  margin-bottom: 1rem;
-}
-.field {
-  margin-bottom: 1rem;
-}
-.field label {
-  display: block;
-  font-size: 0.9rem;
-  font-weight: 600;
-  margin-bottom: 0.35rem;
-}
-.input {
-  width: 100%;
-  padding: 0.5rem 0.75rem;
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-sm);
-  font-size: 0.95rem;
-  background: var(--fs-surface-page);
-  color: var(--fs-text-primary);
-  box-sizing: border-box;
-}
-.input:focus {
-  outline: none;
-  border-color: var(--fs-accent);
-}
-.error-msg {
-  color: var(--fs-error);
-  font-size: 0.9rem;
-  margin: 0 0 0.75rem;
-}
-.success-msg {
-  text-align: center;
-  color: var(--fs-text-secondary);
-  font-size: 0.95rem;
-  padding: 0.5rem 0;
-}
-.success-msg p {
-  margin: 0.5rem 0;
-}
-.auth-footer {
-  text-align: center;
-  font-size: 0.9rem;
-  color: var(--fs-text-secondary);
-  margin: 1rem 0 0;
-}
-.auth-footer a {
-  color: var(--fs-accent);
-}
-</style>
+<style src="@/assets/auth-shared.css" />
@@ -3,6 +3,7 @@ import { ref, computed, onMounted } from "vue";
 import { useRouter, useRoute } from "vue-router";
 import { useAuthStore } from "@/stores/auth";
 import AppLogo from "@/components/AppLogo.vue";
+import { apiErrorMessage } from "@/api/client";

 const router = useRouter();
 const route = useRoute();
@@ -30,12 +31,7 @@ async function handleSubmit() {
    const redirect = (route.query.redirect as string) || "/";
    router.push(redirect);
  } catch (e: unknown) {
-    if (e && typeof e === "object" && "body" in e) {
-      const body = (e as { body?: { error?: string } }).body;
-      error.value = body?.error || "Login failed";
-    } else {
-      error.value = "Login failed";
-    }
+    error.value = apiErrorMessage(e, "Login failed");
  } finally {
    submitting.value = false;
  }
@@ -112,70 +108,8 @@ function loginWithOAuth() {
  </main>
 </template>

+<style src="@/assets/auth-shared.css" />
 <style scoped>
-.auth-page {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  min-height: 100vh;
-  padding: 1rem;
-}
-.auth-card {
-  width: 100%;
-  max-width: 400px;
-  background: var(--fs-surface-raised);
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-lg);
-  padding: 2rem;
-}
-.auth-brand {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  gap: 0.5rem;
-  margin-bottom: 1.5rem;
-}
-.auth-card h1 {
-  margin: 0;
-  text-align: center;
-}
-.auth-hint {
-  text-align: center;
-  font-size: 0.9rem;
-  color: var(--fs-text-secondary);
-  margin-bottom: 1rem;
-}
-.auth-hint a {
-  color: var(--fs-accent);
-}
-.field {
-  margin-bottom: 1rem;
-}
-.field label {
-  display: block;
-  font-size: 0.9rem;
-  font-weight: 600;
-  margin-bottom: 0.35rem;
-}
-.input {
-  width: 100%;
-  padding: 0.5rem 0.75rem;
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-sm);
-  font-size: 0.95rem;
-  background: var(--fs-surface-page);
-  color: var(--fs-text-primary);
-  box-sizing: border-box;
-}
-.input:focus {
-  outline: none;
-  border-color: var(--fs-accent);
-}
-.error-msg {
-  color: var(--fs-error);
-  font-size: 0.9rem;
-  margin: 0 0 0.75rem;
-}
 .divider {
  display: flex;
  align-items: center;
@@ -190,15 +124,6 @@ function loginWithOAuth() {
  flex: 1;
  border-top: 1px solid var(--fs-border-color);
 }
-.auth-footer {
-  text-align: center;
-  font-size: 0.9rem;
-  color: var(--fs-text-secondary);
-  margin: 1rem 0 0;
-}
-.auth-footer a {
-  color: var(--fs-accent);
-}
 .forgot-link {
  text-align: right;
  margin: -0.5rem 0 0.75rem;
@@ -3,6 +3,7 @@ import { ref, onMounted, watch } from "vue";
 import { apiGet } from "@/api/client";
 import { useToastStore } from "@/stores/toast";
 import PaginationBar from "@/components/PaginationBar.vue";
+import { fmtLogStamp } from "@/utils/dateFormat";

 const toastStore = useToastStore();

@@ -98,17 +99,6 @@ function toggleExpand(id: number) {
  expandedId.value = expandedId.value === id ? null : id;
 }

-function formatTime(iso: string): string {
-  const d = new Date(iso);
-  return d.toLocaleString(undefined, {
-    month: "short",
-    day: "numeric",
-    hour: "2-digit",
-    minute: "2-digit",
-    second: "2-digit",
-  });
-}
-
 function formatDetails(details: string | null): string {
  if (!details) return "";
  try {
@@ -210,7 +200,7 @@ function clearFilters() {
                :class="{ 'row-expanded': expandedId === entry.id }"
                @click="toggleExpand(entry.id)"
              >
-                <td class="cell-time">{{ formatTime(entry.created_at) }}</td>
+                <td class="cell-time">{{ fmtLogStamp(entry.created_at) }}</td>
                <td>
                  <span class="category-badge" :class="'cat-' + entry.category">
                    {{ entry.category }}
@@ -559,24 +559,8 @@ function overallPct(project: Project): { total: number; pct: number } {
  color: var(--fs-text-tertiary);
 }

-/* Modal */
-.modal-overlay {
-  position: fixed;
-  inset: 0;
-  background: var(--fs-overlay);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  z-index: 200;
-}
 .modal-card {
-  background: var(--fs-surface-raised);
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-lg);
-  padding: 1.5rem;
-  width: 100%;
  max-width: 480px;
-  box-shadow: 0 8px 32px var(--color-shadow);
  display: flex;
  flex-direction: column;
  gap: 1rem;
@@ -618,36 +602,6 @@ function overallPct(project: Project): { total: number; pct: number } {
 .modal-textarea {
  resize: vertical;
 }
-.modal-actions {
-  display: flex;
-  justify-content: flex-end;
-  gap: 0.5rem;
-}
-.modal-btn {
-  padding: 0.4rem 0.9rem;
-  border: 1px solid var(--fs-border-color);
-  background: var(--fs-surface-raised);
-  color: var(--fs-text-primary);
-  border-radius: var(--fs-radius-sm);
-  cursor: pointer;
-  font-size: 0.875rem;
-  font-family: inherit;
-}
-.modal-btn:hover {
-  background: var(--fs-surface-page);
-}
-.modal-btn-primary {
-  background: var(--fs-action-primary);
-  border-color: var(--fs-action-primary);
-  color: var(--fs-text-on-action);
-}
-.modal-btn-primary:hover:not(:disabled) {
-  opacity: 0.9;
-}
-.modal-btn-primary:disabled {
-  opacity: 0.5;
-  cursor: default;
-}

@media (max-width: 600px) {
  .projects-grid {
@@ -754,7 +754,7 @@ async function confirmDelete() {
          </div>
          <div v-if="coverage.counts" class="coverage-gaps">
            <span
-              v-for="k in ['canonical', 'instance', 'variant', 'exempt']"
+              v-for="k in ['canonical', 'instance', 'variant', 'exempt', 'scoped']"
              :key="k"
            >
              <span v-if="coverage.counts[k]" class="coverage-gap-chip">
@@ -1815,31 +1815,6 @@ async function confirmDelete() {
  display: flex; align-items: center; justify-content: center;
  z-index: 200;
 }
-.modal-card {
-  background: var(--fs-surface-raised);
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-lg);
-  padding: 1.5rem;
-  width: 100%;
-  max-width: 400px;
-  box-shadow: 0 8px 32px var(--color-shadow);
-}
-.modal-title { margin: 0 0 0.75rem; font-size: 1.05rem; }
-.modal-message { font-size: 0.9rem; color: var(--fs-text-secondary); margin: 0 0 1.25rem; line-height: 1.5; }
-.modal-actions { display: flex; justify-content: flex-end; gap: 0.5rem; }
-.modal-btn {
-  padding: 0.4rem 0.9rem;
-  border: 1px solid var(--fs-border-color);
-  background: var(--fs-surface-raised);
-  color: var(--fs-text-primary);
-  border-radius: var(--fs-radius-sm);
-  cursor: pointer;
-  font-size: 0.875rem;
-  font-family: inherit;
-}
-.modal-btn:hover { background: var(--fs-surface-page); }
-.modal-btn-danger { background: var(--fs-action-destructive); border-color: var(--fs-action-destructive); color: var(--fs-text-on-action); }
-.modal-btn-danger:hover { background: var(--fs-action-destructive-hover); border-color: var(--fs-action-destructive-hover); }

 /* ── Skeleton ────────────────────────────────────────────────── */
@keyframes skel-shine { to { background-position: 200% center; } }
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { ref, computed, onMounted } from "vue";
 import { useRoute, useRouter } from "vue-router";
-import { apiGet, apiPost } from "@/api/client";
+import { apiGet, apiPost, apiErrorMessage } from "@/api/client";
 import { useAuthStore } from "@/stores/auth";
 import AppLogo from "@/components/AppLogo.vue";

@@ -68,12 +68,7 @@ async function handleSubmit() {
    await authStore.checkAuth();
    router.push("/");
  } catch (e: unknown) {
-    if (e && typeof e === "object" && "body" in e) {
-      const body = (e as { body?: { error?: string } }).body;
-      error.value = body?.error || "Registration failed";
-    } else {
-      error.value = "Registration failed";
-    }
+    error.value = apiErrorMessage(e, "Registration failed");
  } finally {
    submitting.value = false;
  }
@@ -85,9 +80,9 @@ async function handleSubmit() {
    <div class="auth-card">
      <div class="auth-brand"><AppLogo :size="32" /><h1>Accept Invitation</h1></div>

-      <div v-if="validating" class="loading-msg">Validating invitation...</div>
+      <div v-if="validating" class="auth-loading">Validating invitation...</div>

-      <div v-else-if="!token || !valid" class="error-block">
+      <div v-else-if="!token || !valid" class="auth-note">
        <p>This invitation link is invalid or has expired.</p>
        <p class="auth-footer">
          <router-link to="/login">Back to Sign In</router-link>
@@ -157,103 +152,4 @@ async function handleSubmit() {
  </main>
 </template>

-<style scoped>
-.auth-page {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  min-height: 100vh;
-  padding: 1rem;
-}
-.auth-card {
-  width: 100%;
-  max-width: 400px;
-  background: var(--fs-surface-raised);
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-lg);
-  padding: 2rem;
-}
-.auth-brand {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  gap: 0.5rem;
-  margin-bottom: 1.5rem;
-}
-.auth-card h1 {
-  margin: 0;
-  text-align: center;
-}
-.loading-msg {
-  text-align: center;
-  color: var(--fs-text-tertiary);
-  font-size: 0.95rem;
-  padding: 1rem 0;
-}
-.error-block {
-  text-align: center;
-  color: var(--fs-text-secondary);
-  font-size: 0.95rem;
-  padding: 0.5rem 0;
-}
-.error-block p {
-  margin: 0.5rem 0;
-}
-.field {
-  margin-bottom: 1rem;
-}
-.field label {
-  display: block;
-  font-size: 0.9rem;
-  font-weight: 600;
-  margin-bottom: 0.35rem;
-}
-.input {
-  width: 100%;
-  padding: 0.5rem 0.75rem;
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-sm);
-  font-size: 0.95rem;
-  background: var(--fs-surface-page);
-  color: var(--fs-text-primary);
-  box-sizing: border-box;
-}
-.input:disabled {
-  opacity: 0.6;
-  cursor: not-allowed;
-}
-.input:focus {
-  outline: none;
-  border-color: var(--fs-accent);
-}
-.input-error {
-  border-color: var(--fs-error);
-}
-.input-error:focus {
-  border-color: var(--fs-error);
-}
-.field-hint {
-  margin: 0.35rem 0 0;
-  font-size: 0.8rem;
-  color: var(--fs-text-tertiary);
-}
-.error-hint {
-  margin: 0.35rem 0 0;
-  font-size: 0.8rem;
-  color: var(--fs-error);
-}
-.error-msg {
-  color: var(--fs-error);
-  font-size: 0.9rem;
-  margin: 0 0 0.75rem;
-}
-.auth-footer {
-  text-align: center;
-  font-size: 0.9rem;
-  color: var(--fs-text-secondary);
-  margin: 1rem 0 0;
-}
-.auth-footer a {
-  color: var(--fs-accent);
-}
-</style>
+<style src="@/assets/auth-shared.css" />
@@ -3,6 +3,7 @@ import { ref, computed, onMounted } from "vue";
 import { useRouter } from "vue-router";
 import { useAuthStore } from "@/stores/auth";
 import AppLogo from "@/components/AppLogo.vue";
+import { apiErrorMessage } from "@/api/client";

 const router = useRouter();
 const authStore = useAuthStore();
@@ -39,12 +40,7 @@ async function handleSubmit() {
    await authStore.register(username.value, password.value, email.value || undefined);
    router.push("/");
  } catch (e: unknown) {
-    if (e && typeof e === "object" && "body" in e) {
-      const body = (e as { body?: { error?: string } }).body;
-      error.value = body?.error || "Registration failed";
-    } else {
-      error.value = "Registration failed";
-    }
+    error.value = apiErrorMessage(e, "Registration failed");
  } finally {
    submitting.value = false;
  }
@@ -56,9 +52,9 @@ async function handleSubmit() {
    <div class="auth-card">
      <div class="auth-brand"><AppLogo :size="32" /><h1>Create Account</h1></div>

-      <div v-if="checking" class="loading-msg">Checking registration status...</div>
+      <div v-if="checking" class="auth-loading">Checking registration status...</div>

-      <div v-else-if="!authStore.registrationOpen" class="closed-msg">
+      <div v-else-if="!authStore.registrationOpen" class="auth-note">
        <p>Registration is currently closed.</p>
        <p>Contact an administrator to get an account.</p>
        <p class="auth-footer">
@@ -130,99 +126,4 @@ async function handleSubmit() {
  </main>
 </template>

-<style scoped>
-.auth-page {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  min-height: 100vh;
-  padding: 1rem;
-}
-.auth-card {
-  width: 100%;
-  max-width: 400px;
-  background: var(--fs-surface-raised);
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-lg);
-  padding: 2rem;
-}
-.auth-brand {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  gap: 0.5rem;
-  margin-bottom: 1.5rem;
-}
-.auth-card h1 {
-  margin: 0;
-  text-align: center;
-}
-.loading-msg {
-  text-align: center;
-  color: var(--fs-text-tertiary);
-  font-size: 0.9rem;
-  padding: 1rem 0;
-}
-.closed-msg {
-  text-align: center;
-  color: var(--fs-text-secondary);
-  font-size: 0.95rem;
-  padding: 0.5rem 0;
-}
-.closed-msg p {
-  margin: 0.5rem 0;
-}
-.field {
-  margin-bottom: 1rem;
-}
-.field label {
-  display: block;
-  font-size: 0.9rem;
-  font-weight: 600;
-  margin-bottom: 0.35rem;
-}
-.input {
-  width: 100%;
-  padding: 0.5rem 0.75rem;
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-sm);
-  font-size: 0.95rem;
-  background: var(--fs-surface-page);
-  color: var(--fs-text-primary);
-  box-sizing: border-box;
-}
-.input:focus {
-  outline: none;
-  border-color: var(--fs-accent);
-}
-.input-error {
-  border-color: var(--fs-error);
-}
-.input-error:focus {
-  border-color: var(--fs-error);
-}
-.field-hint {
-  margin: 0.35rem 0 0;
-  font-size: 0.8rem;
-  color: var(--fs-text-tertiary);
-}
-.error-hint {
-  margin: 0.35rem 0 0;
-  font-size: 0.8rem;
-  color: var(--fs-error);
-}
-.error-msg {
-  color: var(--fs-error);
-  font-size: 0.9rem;
-  margin: 0 0 0.75rem;
-}
-.auth-footer {
-  text-align: center;
-  font-size: 0.9rem;
-  color: var(--fs-text-secondary);
-  margin: 1rem 0 0;
-}
-.auth-footer a {
-  color: var(--fs-accent);
-}
-</style>
+<style src="@/assets/auth-shared.css" />
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { ref, computed } from "vue";
 import { useRoute } from "vue-router";
-import { apiPost } from "@/api/client";
+import { apiPost, apiErrorMessage } from "@/api/client";
 import AppLogo from "@/components/AppLogo.vue";

 const route = useRoute();
@@ -35,12 +35,7 @@ async function handleSubmit() {
    });
    success.value = true;
  } catch (e: unknown) {
-    if (e && typeof e === "object" && "body" in e) {
-      const body = (e as { body?: { error?: string } }).body;
-      error.value = body?.error || "Failed to reset password";
-    } else {
-      error.value = "Failed to reset password";
-    }
+    error.value = apiErrorMessage(e, "Failed to reset password");
  } finally {
    submitting.value = false;
  }
@@ -52,7 +47,7 @@ async function handleSubmit() {
    <div class="auth-card">
      <div class="auth-brand"><AppLogo :size="32" /><h1>Set New Password</h1></div>

-      <div v-if="!token" class="error-block">
+      <div v-if="!token" class="auth-note">
        <p>Invalid reset link. Please request a new password reset.</p>
        <p class="auth-footer">
          <router-link to="/forgot-password">Request new link</router-link>
@@ -94,7 +89,7 @@ async function handleSubmit() {
        </form>
      </template>

-      <div v-else class="success-msg">
+      <div v-else class="auth-note">
        <p>Your password has been reset successfully.</p>
        <p>You can now sign in with your new password.</p>
      </div>
@@ -106,102 +101,4 @@ async function handleSubmit() {
  </main>
 </template>

-<style scoped>
-.auth-page {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  min-height: 100vh;
-  padding: 1rem;
-}
-.auth-card {
-  width: 100%;
-  max-width: 400px;
-  background: var(--fs-surface-raised);
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-lg);
-  padding: 2rem;
-}
-.auth-brand {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  gap: 0.5rem;
-  margin-bottom: 1.5rem;
-}
-.auth-card h1 {
-  margin: 0;
-  text-align: center;
-}
-.error-block {
-  text-align: center;
-  color: var(--fs-text-secondary);
-  font-size: 0.95rem;
-  padding: 0.5rem 0;
-}
-.error-block p {
-  margin: 0.5rem 0;
-}
-.success-msg {
-  text-align: center;
-  color: var(--fs-text-secondary);
-  font-size: 0.95rem;
-  padding: 0.5rem 0;
-}
-.success-msg p {
-  margin: 0.5rem 0;
-}
-.field {
-  margin-bottom: 1rem;
-}
-.field label {
-  display: block;
-  font-size: 0.9rem;
-  font-weight: 600;
-  margin-bottom: 0.35rem;
-}
-.input {
-  width: 100%;
-  padding: 0.5rem 0.75rem;
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-sm);
-  font-size: 0.95rem;
-  background: var(--fs-surface-page);
-  color: var(--fs-text-primary);
-  box-sizing: border-box;
-}
-.input:focus {
-  outline: none;
-  border-color: var(--fs-accent);
-}
-.input-error {
-  border-color: var(--fs-error);
-}
-.input-error:focus {
-  border-color: var(--fs-error);
-}
-.field-hint {
-  margin: 0.35rem 0 0;
-  font-size: 0.8rem;
-  color: var(--fs-text-tertiary);
-}
-.error-hint {
-  margin: 0.35rem 0 0;
-  font-size: 0.8rem;
-  color: var(--fs-error);
-}
-.error-msg {
-  color: var(--fs-error);
-  font-size: 0.9rem;
-  margin: 0 0 0.75rem;
-}
-.auth-footer {
-  text-align: center;
-  font-size: 0.9rem;
-  color: var(--fs-text-secondary);
-  margin: 1rem 0 0;
-}
-.auth-footer a {
-  color: var(--fs-accent);
-}
-</style>
+<style src="@/assets/auth-shared.css" />
@@ -3,10 +3,11 @@ import { ref, computed, watch, onMounted } from "vue";
 import { useSettingsStore } from "@/stores/settings";
 import { useAuthStore } from "@/stores/auth";
 import { useToastStore } from "@/stores/toast";
-import { apiGet, apiPost, apiPut, apiDelete, listGroups, createGroup, deleteGroup, listGroupMembers, addGroupMember, removeGroupMember, searchUsers, listApiKeys, createApiKey as apiCreateApiKey, revokeApiKey as apiRevokeApiKey, getProfile, updateProfile, type ApiKeyEntry, type GroupEntry, type GroupMember, type UserSearchResult, type UserProfile } from "@/api/client";
+import { apiGet, apiPost, apiPut, apiDelete, listGroups, createGroup, deleteGroup, listGroupMembers, addGroupMember, removeGroupMember, searchUsers, listApiKeys, createApiKey as apiCreateApiKey, revokeApiKey as apiRevokeApiKey, getProfile, updateProfile, type ApiKeyEntry, type GroupEntry, type GroupMember, type UserSearchResult, type UserProfile, apiErrorMessage } from "@/api/client";
 import type { User } from "@/types/auth";
 import PaginationBar from "@/components/PaginationBar.vue";
 import TagInput from "@/components/TagInput.vue";
+import { fmtDate, fmtLogStamp } from "@/utils/dateFormat";

 const store = useSettingsStore();
 const authStore = useAuthStore();
@@ -624,12 +625,7 @@ async function changeEmail() {
    emailPassword.value = "";
    toastStore.show("Email updated successfully");
  } catch (e: unknown) {
-    if (e && typeof e === "object" && "body" in e) {
-      const b = (e as { body?: { error?: string } }).body;
-      toastStore.show(b?.error || "Failed to update email", "error");
-    } else {
-      toastStore.show("Failed to update email", "error");
-    }
+    toastStore.show(apiErrorMessage(e, "Failed to update email"), "error");
  } finally {
    changingEmail.value = false;
  }
@@ -663,12 +659,7 @@ async function changePassword() {
    newPassword.value = "";
    confirmNewPassword.value = "";
  } catch (e: unknown) {
-    if (e && typeof e === "object" && "body" in e) {
-      const body = (e as { body?: { error?: string } }).body;
-      toastStore.show(body?.error || "Failed to change password", "error");
-    } else {
-      toastStore.show("Failed to change password", "error");
-    }
+    toastStore.show(apiErrorMessage(e, "Failed to change password"), "error");
  } finally {
    changingPassword.value = false;
  }
@@ -766,12 +757,7 @@ async function sendTestEmail() {
    await apiPost("/api/admin/smtp/test", { recipient: testRecipient.value.trim() });
    toastStore.show("Test email sent successfully");
  } catch (e: unknown) {
-    if (e && typeof e === "object" && "body" in e) {
-      const body = (e as { body?: { error?: string } }).body;
-      toastStore.show(body?.error || "Failed to send test email", "error");
-    } else {
-      toastStore.show("Failed to send test email", "error");
-    }
+    toastStore.show(apiErrorMessage(e, "Failed to send test email"), "error");
  } finally {
    sendingTest.value = false;
  }
@@ -1129,14 +1115,6 @@ function toggleLogExpand(id: number) {
  expandedLogId.value = expandedLogId.value === id ? null : id;
 }

-function formatLogTime(iso: string): string {
-  const d = new Date(iso);
-  return d.toLocaleString(undefined, {
-    month: "short", day: "numeric",
-    hour: "2-digit", minute: "2-digit", second: "2-digit",
-  });
-}
-
 function formatLogDetails(details: string | null): string {
  if (!details) return "";
  try { return JSON.stringify(JSON.parse(details), null, 2); } catch { return details; }
@@ -1224,12 +1202,6 @@ async function deleteUser(userId: number) {
    deleting.value = null;
  }
 }
-
-function formatUserDate(iso: string): string {
-  return new Date(iso).toLocaleDateString(undefined, {
-    year: "numeric", month: "short", day: "numeric",
-  });
-}
 </script>

 <template>
@@ -2355,8 +2327,8 @@ function formatUserDate(iso: string): string {
            <tbody>
              <tr v-for="inv in invitations" :key="inv.id">
                <td class="cell-email">{{ inv.email }}</td>
-                <td class="hide-mobile cell-date">{{ formatUserDate(inv.created_at) }}</td>
-                <td class="hide-mobile cell-date">{{ formatUserDate(inv.expires_at) }}</td>
+                <td class="hide-mobile cell-date">{{ fmtDate(inv.created_at) }}</td>
+                <td class="hide-mobile cell-date">{{ fmtDate(inv.expires_at) }}</td>
                <td class="cell-actions">
                  <button class="btn-ghost btn-compact" @click="revokeInvitation(inv.id)" :disabled="revokingId !== null">
                    {{ revokingId === inv.id ? "Revoking..." : "Revoke" }}
@@ -2391,7 +2363,7 @@ function formatUserDate(iso: string): string {
                  {{ u.role }}
                </span>
              </td>
-              <td class="hide-mobile cell-date">{{ formatUserDate(u.created_at) }}</td>
+              <td class="hide-mobile cell-date">{{ fmtDate(u.created_at) }}</td>
              <td class="cell-actions">
                <template v-if="u.id === authStore.user?.id">
                  <span class="you-label">You</span>
@@ -2474,7 +2446,7 @@ function formatUserDate(iso: string): string {
            <tbody>
              <template v-for="entry in logs" :key="entry.id">
                <tr class="log-row" :class="{ 'row-expanded': expandedLogId === entry.id }" @click="toggleLogExpand(entry.id)">
-                  <td class="cell-time">{{ formatLogTime(entry.created_at) }}</td>
+                  <td class="cell-time">{{ fmtLogStamp(entry.created_at) }}</td>
                  <td>
                    <span class="category-badge" :class="'cat-' + entry.category">{{ entry.category }}</span>
                  </td>
@@ -903,23 +903,8 @@ function usageTitle(s: SnippetListItem): string {
 }

 /* Merge modal */
-.modal-overlay {
-  position: fixed;
-  inset: 0;
-  background: var(--fs-overlay);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  z-index: 200;
-}
 .modal-card {
-  background: var(--fs-surface-raised);
-  border: 1px solid var(--fs-border-color);
-  border-radius: var(--fs-radius-lg);
-  padding: 1.5rem;
-  width: 100%;
  max-width: 460px;
-  box-shadow: 0 8px 32px var(--color-shadow);
  display: flex;
  flex-direction: column;
  gap: 1rem;
@@ -966,36 +951,6 @@ function usageTitle(s: SnippetListItem): string {
  color: var(--fs-text-tertiary);
  flex-shrink: 0;
 }
-.modal-actions {
-  display: flex;
-  justify-content: flex-end;
-  gap: 0.5rem;
-}
-.modal-btn {
-  padding: 0.4rem 0.9rem;
-  border: 1px solid var(--fs-border-color);
-  background: var(--fs-surface-raised);
-  color: var(--fs-text-primary);
-  border-radius: var(--fs-radius-sm);
-  cursor: pointer;
-  font-size: 0.875rem;
-  font-family: inherit;
-}
-.modal-btn:hover {
-  background: var(--fs-surface-page);
-}
-.modal-btn-primary {
-  background: var(--fs-action-primary);
-  border-color: var(--fs-action-primary);
-  color: var(--fs-text-on-action);
-}
-.modal-btn-primary:hover:not(:disabled) {
-  background: var(--fs-action-primary-hover);
-}
-.modal-btn-primary:disabled {
-  opacity: 0.5;
-  cursor: default;
-}

@media (max-width: 600px) {
  .snippets-grid {
@@ -1,9 +1,10 @@
 <script setup lang="ts">
 import { ref, onMounted } from "vue";
-import { apiGet, apiPost, apiPut, apiDelete } from "@/api/client";
+import { apiGet, apiPost, apiPut, apiDelete, apiErrorMessage } from "@/api/client";
 import { useAuthStore } from "@/stores/auth";
 import { useToastStore } from "@/stores/toast";
 import type { User } from "@/types/auth";
+import { fmtDate } from "@/utils/dateFormat";

 interface Invitation {
  id: number;
@@ -69,12 +70,7 @@ async function sendInvite() {
    inviteEmail.value = "";
    await fetchInvitations();
  } catch (e: unknown) {
-    if (e && typeof e === "object" && "body" in e) {
-      const body = (e as { body?: { error?: string } }).body;
-      toastStore.show(body?.error || "Failed to send invitation", "error");
-    } else {
-      toastStore.show("Failed to send invitation", "error");
-    }
+    toastStore.show(apiErrorMessage(e, "Failed to send invitation"), "error");
  } finally {
    sendingInvite.value = false;
  }
@@ -128,24 +124,11 @@ async function deleteUser(userId: number) {
    users.value = users.value.filter((u) => u.id !== userId);
    toastStore.show("User deleted");
  } catch (e: unknown) {
-    if (e && typeof e === "object" && "body" in e) {
-      const body = (e as { body?: { error?: string } }).body;
-      toastStore.show(body?.error || "Failed to delete user", "error");
-    } else {
-      toastStore.show("Failed to delete user", "error");
-    }
+    toastStore.show(apiErrorMessage(e, "Failed to delete user"), "error");
  } finally {
    deleting.value = null;
  }
 }
-
-function formatDate(iso: string): string {
-  return new Date(iso).toLocaleDateString(undefined, {
-    year: "numeric",
-    month: "short",
-    day: "numeric",
-  });
-}
 </script>

 <template>
@@ -212,8 +195,8 @@ function formatDate(iso: string): string {
          <tbody>
            <tr v-for="inv in invitations" :key="inv.id">
              <td class="cell-email">{{ inv.email }}</td>
-              <td class="hide-mobile cell-date">{{ formatDate(inv.created_at) }}</td>
-              <td class="hide-mobile cell-date">{{ formatDate(inv.expires_at) }}</td>
+              <td class="hide-mobile cell-date">{{ fmtDate(inv.created_at) }}</td>
+              <td class="hide-mobile cell-date">{{ fmtDate(inv.expires_at) }}</td>
              <td class="cell-actions">
                <button
                  class="btn-ghost btn-compact"
@@ -255,7 +238,7 @@ function formatDate(iso: string): string {
                {{ u.role }}
              </span>
            </td>
-            <td class="hide-mobile cell-date">{{ formatDate(u.created_at) }}</td>
+            <td class="hide-mobile cell-date">{{ fmtDate(u.created_at) }}</td>
            <td class="cell-actions">
              <template v-if="u.id === authStore.user?.id">
                <span class="you-label">You</span>
@@ -1,7 +1,7 @@
 {
  "name": "scribe",
  "description": "Scribe system-of-record for Claude Code: MCP tools over your notes/tasks/projects/rules, a session-start push channel that surfaces your always-on rules + active-project context, process-skills (writing-plans, systematic-debugging, verification, brainstorming, reusing-code), and your saved Scribe Processes auto-surfaced as skills (/scribe:sync). Replaces superpowers + file-memory with one app-backed plugin.",
-  "version": "0.1.36",
+  "version": "0.1.37",
  "author": { "name": "Bryan Van Deusen" },
  "mcpServers": {
    "scribe": {
@@ -17,6 +17,11 @@ row carries a status:
  — the why IS the record.
 - `exempt` — judged genuinely one-off. **Reason required.** A recorded
  judgment, not silence — it stops the next pass re-litigating it.
+- `scoped` — one-off **by construction**, stamped by the coverage sync
+  (a Vue component's scoped `<style>` rules and its `<script setup>`
+  functions — unreachable from any other file). Accounted for without a
+  judgment; still proposed against, grouped and flagged; any judgment you
+  make overrides it. Not the todo.
 - `unclassified` — nobody has judged it yet. **This is the todo list.**

 ## The loop
@@ -4,20 +4,6 @@ from __future__ import annotations
 from scribe.services.api_keys import lookup_key


-async def resolve_bearer_to_user_id(auth_header: str | None) -> int | None:
-    """Parse an `Authorization: Bearer <token>` header and return the user_id.
-
-    Returns None if the header is missing, malformed, or the token is invalid
-    or revoked. The underlying lookup_key already updates last_used_at on hit.
-    """
-    if not auth_header or not auth_header.startswith("Bearer "):
-        return None
-    raw_token = auth_header[len("Bearer "):].strip()
-    if not raw_token:
-        return None
-    api_key = await lookup_key(raw_token)
-    return api_key.user_id if api_key else None
-

 async def resolve_bearer(auth_header: str | None) -> tuple[int, str] | None:
    """Resolve a Bearer token to (user_id, scope).
@@ -57,9 +57,7 @@ async def get_milestone(milestone_id: int) -> dict:
    return {
        "milestone": out,
        "steps": [t.to_dict() for t in steps],
-        "applicable_rules": applicable["rules"],
-        "subscribed_rulebooks": applicable["subscribed_rulebooks"],
-        "applicable_rules_truncated": applicable["truncated"],
+        **rulebooks_svc.rules_payload(applicable),
    }


@@ -62,30 +62,6 @@ async def list_notes(
    return {"notes": [n.to_dict() for n in rows], "total": total}


-async def _attach_supersession(uid: int, note_id: int, data: dict) -> None:
-    """Add both directions of the supersession relation to a note payload.
-
-    Both, because they answer different questions and only one of them is
-    obvious. `supersedes` is what the author claimed. `superseded_by` is what a
-    READER needs and what the note itself cannot know — a stale record handed
-    over without that marker gets acted on confidently, which is worse than
-    never surfacing it.
-
-    Omitted entirely when empty, so an ordinary note's payload doesn't grow two
-    permanently-empty lists. A field that always says nothing trains readers to
-    skip fields, which is the lesson `consolidated_at` cost us (#2483).
-    """
-    rel = await supersession_svc.get_relations(uid, note_id)
-    if rel["supersedes"]:
-        data["supersedes"] = rel["supersedes"]
-    if rel["superseded_by"]:
-        data["superseded_by"] = rel["superseded_by"]
-        data["superseded_note"] = (
-            "A later note claims to bring this up to date — see superseded_by. "
-            "Read this as what was true when written, and check the newer one "
-            "before acting on it."
-        )
-

 async def get_note(note_id: int) -> dict:
    """Fetch the full content of a single Scribe note by its ID.
@@ -113,7 +89,7 @@ async def get_note(note_id: int) -> dict:
    # snippets would leave those permanently at zero pulls and make them look
    # like dead weight next to snippets that merely had a counter (#2085).
    record_pulled(user_id=uid, note_id=int(note.id), source="mcp_get_note")
-    await _attach_supersession(uid, note_id, out)
+    await supersession_svc.attach_relations(uid, note_id, out, hint=True)
    await systems_tools.attach_systems(
        uid, getattr(note, "user_id", uid) or uid, out, note.id, note.project_id
    )
@@ -186,7 +162,7 @@ async def create_note(
            raise ValueError(str(exc)) from exc
    data = note.to_dict()
    await systems_tools.attach_systems(uid, uid, data, note.id, project_id or None)
-    await _attach_supersession(uid, note.id, data)
+    await supersession_svc.attach_relations(uid, note.id, data, hint=True)
    return data


@@ -237,7 +213,7 @@ async def update_note(
    await systems_tools.attach_systems(
        uid, getattr(note, "user_id", uid) or uid, data, note_id, note.project_id
    )
-    await _attach_supersession(uid, note_id, data)
+    await supersession_svc.attach_relations(uid, note_id, data, hint=True)
    return data


@@ -192,12 +192,7 @@ async def enter_project(project_id: int) -> dict:
        ],
        "design_system": design_system,
        "milestone_summary": milestone_summary,
-        "applicable_rules": applicable["rules"],
-        "project_rules": applicable.get("project_rules", []),
-        "suppressed_rules": applicable.get("suppressed_rules", []),
-        "suppressed_topics": applicable.get("suppressed_topics", []),
-        "subscribed_rulebooks": applicable["subscribed_rulebooks"],
-        "applicable_rules_truncated": applicable["truncated"],
+        **rulebooks_svc.rules_payload(applicable),
        "open_tasks": [
            {
                "id": t.id, "title": t.title, "status": t.status,
@@ -239,12 +234,7 @@ async def get_project(project_id: int) -> dict:
    applicable = await rulebooks_svc.get_applicable_rules(
        project_id=project_id, user_id=uid,
    )
-    data["applicable_rules"] = applicable["rules"]
-    data["applicable_rules_truncated"] = applicable["truncated"]
-    data["subscribed_rulebooks"] = applicable["subscribed_rulebooks"]
-    data["project_rules"] = applicable.get("project_rules", [])
-    data["suppressed_rules"] = applicable.get("suppressed_rules", [])
-    data["suppressed_topics"] = applicable.get("suppressed_topics", [])
+    data.update(rulebooks_svc.rules_payload(applicable))
    return data


@@ -13,28 +13,43 @@ from scribe.services import projects as projects_svc
 from scribe.services import repo_bindings as repo_bindings_svc


-async def bind_repo(repo_url: str, project_id: int) -> dict:
+async def bind_repo(repo_url: str, project_id: int, ref: str = "") -> dict:
    """Bind a git repository to a Scribe project for session-start context.

    After this, any session started in that repo auto-loads the project's
    context (the SessionStart hook sends the repo's remote; the server resolves
    it here). Idempotent — re-binding the same repo updates the target project.

+    The binding is also what the shape ledger reads (refresh_pattern_coverage):
+    `ref` names the branch it follows. Default (""): the repo's default branch
+    — which means the ledger only sees work after a merge. A dev-first project
+    (rule 1: dev is home) should bind with ref="dev" so classification follows
+    the push, not the merge. Re-binding with ref="" keeps the standing ref;
+    pass ref="-" to clear it back to the default branch.
+
    Args:
        repo_url: the repo's git remote (e.g. the output of
            `git remote get-url origin` — ssh or https form, both work).
        project_id: the Scribe project this repo represents.
+        ref: branch the ledger follows ("" = leave as is / default branch on
+            a new binding; "-" = clear to the default branch).
    """
    uid = current_user_id()
    project = await projects_svc.get_project(uid, project_id)
    if project is None:
        raise ValueError(f"project {project_id} not found")
-    binding = await repo_bindings_svc.set_binding(uid, repo_url, project_id)
+    ref_arg = None if not ref else ("" if ref.strip() == "-" else ref)
+    binding = await repo_bindings_svc.set_binding(uid, repo_url, project_id, ref_arg)
+    follows = binding.ref or "the default branch"
    return {
        "repo_key": binding.repo_key,
        "project_id": binding.project_id,
        "project_title": project.title,
-        "message": f"Bound `{binding.repo_key}` -> {project.title} (id {project.id}).",
+        "ref": binding.ref,
+        "message": (
+            f"Bound `{binding.repo_key}` -> {project.title} (id {project.id}); "
+            f"the ledger follows {follows}."
+        ),
    }


@@ -193,6 +193,12 @@ async def delete_topic(topic_id: int, confirmed: bool = False) -> dict:

 # ── Rule CRUD ──────────────────────────────────────────────────────────

+def _rule_summary(r) -> 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."""
+    return {"id": r.id, "title": r.title, "statement": r.statement, "topic_id": r.topic_id}
+
+
 async def list_rules(
    rulebook_id: int = 0, topic_id: int = 0, project_id: int = 0,
 ) -> dict:
@@ -213,16 +219,7 @@ async def list_rules(
        topic_id=topic_id or None,
        project_id=project_id or None,
    )
-    return {
-        "rules": [
-            {
-                "id": r.id, "title": r.title, "statement": r.statement,
-                "topic_id": r.topic_id,
-            }
-            for r in rows
-        ],
-        "total": len(rows),
-    }
+    return {"rules": [_rule_summary(r) for r in rows], "total": len(rows)}


 async def list_always_on_rules() -> dict:
@@ -235,16 +232,7 @@ async def list_always_on_rules() -> dict:
    """
    uid = current_user_id()
    rules = await rulebooks_svc.list_always_on_rules(uid)
-    return {
-        "rules": [
-            {
-                "id": r.id, "title": r.title, "statement": r.statement,
-                "topic_id": r.topic_id,
-            }
-            for r in rules
-        ],
-        "total": len(rules),
-    }
+    return {"rules": [_rule_summary(r) for r in rules], "total": len(rules)}


 async def get_rule(rule_id: int) -> dict:
@@ -36,10 +36,20 @@ async def classify_shapes(
    Args:
        project_id: The project whose ledger is being judged.
        classifications: Objects of {path, symbol, status, kind?, snippet_id?,
-            reason?}. path+symbol name the shape exactly as list_shapes shows
-            it; kind ("sym"/"css") narrows when one file defines both.
-            snippet_id is required for canonical/instance/variant; reason is
-            required for variant/exempt.
+            reason?, reason_code?}. path+symbol name the shape exactly as
+            list_shapes shows it; kind ("sym"/"css") narrows when one file
+            defines both. snippet_id is required for canonical/instance/
+            variant; reason is required for variant/exempt. reason_code is
+            an OPTIONAL index beside the prose (one of: scoped-css,
+            one-off-handler, test-helper, convention-plumbing, pure-helper,
+            generated, script, typed-record) so the ledger can be filtered
+            and aggregated by kind of one-off — the prose stays the record.
+            uses is an OPTIONAL list of snippet ids this shape CALLS (#2870):
+            conformance (status + snippet_id) says what shape it is, uses
+            says which canonical helpers it consumes — a service function
+            can be an instance of the service-function convention AND use
+            hash_token. Consumer maps are uses edges; list_shapes(uses=N)
+            and get_snippet's `uses` read them.
        via: Who is judging — "agent" (default), "audit" (a sweep), or
            "import" (carrying maps recorded elsewhere).

@@ -64,6 +74,8 @@ async def list_shapes(
    offset: int = 0,
    proposal: str = "",
    flag: str = "",
+    compact: bool = False,
+    uses: int = 0,
 ) -> dict:
    """Read a project's shape ledger — `status="unclassified"` IS the todo.

@@ -71,12 +83,27 @@ async def list_shapes(
    (fed by the coverage refresh). Filters compose:

    Args:
-        status: canonical | instance | variant | exempt | unclassified.
+        status: canonical | instance | variant | exempt | scoped | unclassified.
+            `scoped` (#2869) is the sync's mechanical stamp on one-offs by
+            construction (a Vue component's scoped <style> rules and its
+            <script setup> functions): accounted for, not judged, still
+            proposed against / grouped / flagged, and overridable by any
+            classify_shapes judgment. The human todo is `unclassified`.
        path: exact file, or a directory — matches everything beneath it
            (the coverage line's "largest" dirs go straight in here).
-        snippet_id: rows classified against this snippet — a consumer map.
+        snippet_id: rows classified against this snippet (instance/variant
+            of it — conformance).
+        uses: rows that CALL this snippet (#2870) — the consumer map proper,
+            whatever shape each row is itself; edges come from judgments
+            (classify_shapes uses=), the write-path hook, and the proposer's
+            by-name reference hits.
        include_vanished: include shapes no longer in the tree (history).
        limit/offset: page through big ledgers (limit caps at 500).
+        compact: rows as `path · symbol · kind · status · signature` plus
+            snippet_id / by / proposal / diverges_from / recheck only when
+            set — no commits, shas or timestamps. THE form for an audit:
+            a full 500-row page fits the tool budget. The default rows carry
+            everything (shape_history-grade bookkeeping).
        proposal: the proposer's queue (#2792) — "any", "canon" (rows the
            machine thinks are an instance of a snippet: `proposal` carries
            snippet_id, basis, score), "derive" (rows that repeat with NO
@@ -116,9 +143,73 @@ async def list_shapes(
        uid, project_id,
        status=status, path=path, snippet_id=snippet_id,
        include_vanished=include_vanished, limit=limit, offset=offset,
-        proposal=proposal, flag=flag,
+        proposal=proposal, flag=flag, uses=uses,
    )
-    return {"shapes": [r.to_dict() for r in rows], "total": total}
+    return {
+        "shapes": [r.to_compact() if compact else r.to_dict() for r in rows],
+        "total": total,
+    }
+
+
+async def classify_shapes_by_rule(
+    project_id: int,
+    path: str,
+    status: str,
+    pattern: str = "",
+    kind: str = "",
+    snippet_id: int = 0,
+    reason: str = "",
+    via: str = "agent",
+    include_judged: bool = False,
+    reason_code: str = "",
+    uses: list[int] | None = None,
+) -> dict:
+    """The sweep form of classify_shapes: ONE judgment applied to every
+    unclassified shape under a directory whose symbol matches a glob.
+
+    For the long tail an audit judges by family, not by row — "every scoped
+    rule under frontend/src/views is exempt: styles one element of its view",
+    "every `*_scheduler.py` symbol is an instance of ScheduledJob" — where
+    listing 900 rows and sending them back is the whole cost. The row form
+    stays the precise tool; reach for it when each row gets its own reason.
+
+    Args:
+        project_id: The project whose ledger is being judged.
+        path: A file, or a directory and everything beneath it. Required —
+            a sweep names what it judges.
+        status: instance | variant | exempt | unclassified (canonical is the
+            sync's stamp, not a sweep's).
+        pattern: Shell glob on the symbol (`*_rows`, `_*`, `modal-*`, `*`);
+            "" = every symbol under path.
+        kind: "sym" or "css" to narrow; "" = both.
+        snippet_id: Required for instance/variant — the canon judged against.
+        reason: Required for variant/exempt — the why, recorded on every row.
+        via: "agent" (default) | "audit" | "import".
+        reason_code: Optional catalogue code beside the reason (see
+            classify_shapes) — a sweep is exactly where one applies.
+        uses: Optional snippet ids every matched shape CALLS (#2870) — e.g.
+            "every *_scheduler.py symbol uses ScheduledJob".
+        include_judged: By default only unjudged rows are touched —
+            `unclassified` and the sync's mechanical `scoped` stamp — a
+            sweep never silently overwrites a judgment. True re-judges every
+            matching live row (use to re-confirm after a recheck, or to
+            revise a family you judged earlier).
+
+    One transaction: applies whole or not at all. Returns
+    {"classified": N, "sample": ["path::symbol", ...]} (first 12, sorted)
+    so you can see what the rule reached; N = 0 means the rule matched
+    nothing live and unclassified — widen the pattern or refresh coverage.
+    """
+    uid = current_user_id()
+    try:
+        return await shape_ledger_svc.classify_shapes_where(
+            uid, project_id, path=path, status=status, pattern=pattern,
+            kind=kind, snippet_id=snippet_id or None, reason=reason or None,
+            via=via, include_judged=include_judged,
+            reason_code=reason_code or None, uses=uses or None,
+        )
+    except ValueError as exc:
+        return {"error": str(exc)}


 async def shape_history(
@@ -217,7 +308,7 @@ async def refresh_pattern_coverage(project_id: int) -> dict:

 def register(mcp) -> None:
    for fn in (
-        classify_shapes, list_shapes, refresh_pattern_coverage,
-        confirm_shape_proposals, shape_history,
+        classify_shapes, classify_shapes_by_rule, list_shapes,
+        refresh_pattern_coverage, confirm_shape_proposals, shape_history,
    ):
        mcp.tool(name=fn.__name__)(fn)
@@ -245,6 +245,10 @@ async def get_snippet(snippet_id: int) -> dict:
        data["instances"] = consumers["instances"]
    if consumers["variants"]:
        data["variants"] = consumers["variants"]
+    if consumers.get("uses"):
+        # The call sites (#2870): shapes that use this snippet, whatever
+        # shape they are themselves.
+        data["uses"] = consumers["uses"]
    return data


@@ -134,7 +134,7 @@ async def attach_systems(
    tagged record shows its areas (the touching-a-System reflex needs the
    affiliation visible on read, not just settable on write), an untagged
    project record carries the question instead. Neither field is ever
-    attached empty (same reasoning as notes._attach_supersession / #2483 — a
+    attached empty (same reasoning as supersession_svc.attach_relations / #2483 — a
    field that always says nothing trains readers to skip fields). The hint
    goes only to the record's owner: tagging someone else's record in someone
    else's project is not the caller's call to make. Fail-open — decoration
@@ -97,12 +97,7 @@ async def get_task(task_id: int) -> dict:
        applicable = await rulebooks_svc.get_applicable_rules(
            project_id=note.project_id, user_id=uid,
        )
-        data["applicable_rules"] = applicable["rules"]
-        data["subscribed_rulebooks"] = applicable["subscribed_rulebooks"]
-        data["applicable_rules_truncated"] = applicable["truncated"]
-        data["project_rules"] = applicable.get("project_rules", [])
-        data["suppressed_rules"] = applicable.get("suppressed_rules", [])
-        data["suppressed_topics"] = applicable.get("suppressed_topics", [])
+        data.update(rulebooks_svc.rules_payload(applicable))
    data.update(await access_svc.describe_provenance(uid, note))
    # Same reasoning as get_note's record_pulled, and this is the tool where it
    # matters MOST: auto-inject ranks kind-blind over a corpus that is
@@ -44,6 +44,6 @@ from scribe.models.rulebook import (  # noqa: E402, F401
 )
 from scribe.models.repo_binding import RepoBinding  # noqa: E402, F401
 from scribe.models.forge_connection import ForgeConnection  # noqa: E402, F401
-from scribe.models.code_shape import CodeShape, CodeShapeEvent  # noqa: E402, F401
+from scribe.models.code_shape import CodeShape, CodeShapeEvent, CodeShapeUse  # noqa: E402, F401
 from scribe.models.system import System, RecordSystem  # noqa: E402, F401
 from scribe.models.design_system import DesignSystem, DesignToken  # noqa: E402, F401
@@ -4,7 +4,7 @@ from sqlalchemy import DateTime, ForeignKey, Index, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import CreatedAtMixin
+from scribe.models.base import CreatedAtMixin, iso


 class ApiKey(Base, CreatedAtMixin):
@@ -36,7 +36,7 @@ class ApiKey(Base, CreatedAtMixin):
            "name": self.name,
            "key_prefix": self.key_prefix,
            "scope": self.scope,
-            "last_used_at": self.last_used_at.isoformat() if self.last_used_at else None,
-            "created_at": self.created_at.isoformat(),
-            "revoked_at": self.revoked_at.isoformat() if self.revoked_at else None,
+            "last_used_at": iso(self.last_used_at),
+            "created_at": iso(self.created_at),
+            "revoked_at": iso(self.revoked_at),
        }
@@ -4,6 +4,7 @@ from sqlalchemy import DateTime, Float, Index, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
+from scribe.models.base import iso


 class AppLog(Base):
@@ -20,6 +21,9 @@ class AppLog(Base):
    duration_ms: Mapped[float | None] = mapped_column(Float, nullable=True)
    ip_address: Mapped[str | None] = mapped_column(Text, nullable=True)
    details: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # Declared here rather than via CreatedAtMixin on purpose: the composite
+    # index below orders on `created_at.desc()`, which needs the column object
+    # in this class body — a mixin's column is not in scope there.
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
    )
@@ -44,5 +48,5 @@ class AppLog(Base):
            "duration_ms": self.duration_ms,
            "ip_address": self.ip_address,
            "details": self.details,
-            "created_at": self.created_at.isoformat() if self.created_at else None,
+            "created_at": iso(self.created_at),
        }
@@ -1,9 +1,19 @@
-from datetime import datetime, timezone
+from datetime import date, datetime, timezone

 from sqlalchemy import DateTime, Text
 from sqlalchemy.orm import Mapped, mapped_column


+def iso(value: datetime | date | None) -> str | None:
+    """ISO-8601 for a payload, None for an unset column.
+
+    Every model's to_dict serialises timestamps through this one helper so a
+    row read before flush (created_at still None) and a nullable column both
+    come out as null instead of raising on `.isoformat()`.
+    """
+    return value.isoformat() if value else None
+
+
 class SoftDeleteMixin:
    """Recoverable-delete columns. NULL deleted_at = live row. deleted_batch_id
    groups rows soft-deleted in one operation so a cascade restores as a unit."""
@@ -1,4 +1,4 @@
-from datetime import datetime
+from datetime import datetime, timezone

 from sqlalchemy import (
    BigInteger,
@@ -13,13 +13,33 @@ from sqlalchemy import (
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import TimestampMixin
+from scribe.models.base import TimestampMixin, iso

 # The classification vocabulary (note 2786). `unclassified` is the default and
-# THE todo state; every other status is a judgment, stamped with who made it.
-SHAPE_STATUSES = ("canonical", "instance", "variant", "exempt", "unclassified")
+# THE todo state; every other status is a judgment, stamped with who made it —
+# except `scoped` (#2869): the coverage sync's mechanical stamp on shapes that
+# are one-offs BY CONSTRUCTION (a Vue component's scoped <style> rules and its
+# <script setup> functions — unreachable from any other file). Scoped rows are
+# accounted for without a human judging them, so `exempt` keeps meaning "a
+# person looked"; the proposer, derive grouping and divergence still see them,
+# and any judgment (instance/variant/exempt) overrides the stamp.
+SHAPE_STATUSES = ("canonical", "instance", "variant", "exempt", "scoped", "unclassified")
 SHAPE_CLASSIFIERS = ("agent", "audit", "hook", "mechanical", "import")

+# The reason catalogue (#2874): an OPTIONAL code beside the prose reason on
+# variant/exempt rows, so the ledger can be filtered and aggregated by kind
+# of one-off. The prose remains the record; the code is the index.
+REASON_CODES = (
+    "scoped-css",            # a scoped rule styling one element (pre-#2869 rows)
+    "one-off-handler",       # a view/component handler or loader, one per surface
+    "test-helper",           # a test module's stub, driver or fixture data
+    "convention-plumbing",   # registration, wiring, app factory — one of each
+    "pure-helper",           # a sync module-private helper with no session
+    "generated",             # generated source (theme.css, protos, bundles)
+    "script",                # a standalone dev/CI script
+    "typed-record",          # a NamedTuple / dataclass / error class — one each
+)
+
 # How the mechanical proposer (#2792) arrived at a proposal, strongest first.
 # `derive` is the odd one out: not "this is an instance of #N" but "this
 # shape repeats with NO canon — derive one first" (note 2786's derive-first
@@ -99,6 +119,7 @@ class CodeShape(Base, TimestampMixin):
        BigInteger, ForeignKey("notes.id", ondelete="SET NULL"), nullable=True
    )
    reason: Mapped[str | None] = mapped_column(Text, nullable=True)
+    reason_code: Mapped[str | None] = mapped_column(Text, nullable=True)   # REASON_CODES (#2874)
    classified_by: Mapped[str | None] = mapped_column(Text, nullable=True)
    classified_at: Mapped[datetime | None] = mapped_column(
        DateTime(timezone=True), nullable=True
@@ -152,19 +173,95 @@ class CodeShape(Base, TimestampMixin):
            "status": self.status,
            "snippet_id": self.snippet_id,
            "reason": self.reason,
+            "reason_code": self.reason_code,
            "classified_by": self.classified_by,
-            "classified_at": self.classified_at.isoformat() if self.classified_at else None,
+            "classified_at": iso(self.classified_at),
            "first_seen_commit": self.first_seen_commit,
            "last_seen_commit": self.last_seen_commit,
-            "vanished_at": self.vanished_at.isoformat() if self.vanished_at else None,
+            "vanished_at": iso(self.vanished_at),
            "signature": self.signature,
            "body_sha": self.body_sha,
            "proposal": self.proposal,
            "classified_sha": self.classified_sha,
-            "recheck_at": self.recheck_at.isoformat() if self.recheck_at else None,
+            "recheck_at": iso(self.recheck_at),
            "diverges_from": self.diverges_from,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
+        }
+
+    def to_compact(self) -> dict:
+        """The row as an audit reads it (#2868): identity, standing, the
+        definition line and the proposer's word — none of the bookkeeping
+        (commits, shas, timestamps). A 500-row page of these fits the tool
+        budget; a page of to_dict() does not."""
+        out = {
+            "path": self.path,
+            "symbol": self.symbol,
+            "kind": self.kind,
+            "status": self.status,
+            "signature": self.signature,
+        }
+        if self.snippet_id is not None:
+            out["snippet_id"] = self.snippet_id
+        if self.classified_by:
+            out["by"] = self.classified_by
+        if self.reason_code:
+            out["reason_code"] = self.reason_code
+        proposal = self.proposal
+        if proposal:
+            out["proposal"] = proposal
+        if self.diverges_from is not None:
+            out["diverges_from"] = self.diverges_from
+        if self.recheck_at is not None:
+            out["recheck"] = True
+        return out
+
+
+# How a uses edge was established (#2870): who/what said "this shape calls
+# that canon". `reference` is the proposer's mechanical by-name hit on the
+# body (language-gated, #2871); `hook` is write-path evidence (pulled the
+# snippet, then wrote code naming its symbol); agent/audit/import are
+# judgments carried on classify_shapes(..., uses=[...]).
+USE_BASES = ("reference", "hook", "agent", "audit", "import")
+
+
+class CodeShapeUse(Base):
+    """One consumption edge: shape → canonical snippet it calls/uses (#2870).
+
+    Conformance (CodeShape.status/snippet_id) answers "what shape is this";
+    this table answers "what does it use" — many per shape. A service function
+    that is an instance of the service-function convention AND a consumer of
+    hash_token has one snippet_id and one uses edge. Cascades with both ends:
+    a use of a deleted snippet is no longer a fact worth keeping.
+    """
+
+    __tablename__ = "code_shape_uses"
+    __table_args__ = (
+        UniqueConstraint("shape_id", "snippet_id", name="uq_code_shape_uses_shape_snippet"),
+        Index("ix_code_shape_uses_snippet", "snippet_id"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    shape_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("code_shapes.id", ondelete="CASCADE"), nullable=False
+    )
+    snippet_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("notes.id", ondelete="CASCADE"), nullable=False
+    )
+    basis: Mapped[str] = mapped_column(Text, nullable=False)
+    evidence: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=lambda: datetime.now(timezone.utc)
+    )
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "shape_id": self.shape_id,
+            "snippet_id": self.snippet_id,
+            "basis": self.basis,
+            "evidence": self.evidence,
+            "created_at": iso(self.created_at),
        }


@@ -221,5 +318,5 @@ class CodeShapeEvent(Base):
            "classified_by": self.classified_by,
            "reason": self.reason,
            "commit": self.commit,
-            "at": self.at.isoformat(),
+            "at": iso(self.at),
        }
@@ -20,7 +20,7 @@ from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import SoftDeleteMixin, TimestampMixin
+from scribe.models.base import SoftDeleteMixin, TimestampMixin, iso


 class DesignSystem(Base, TimestampMixin, SoftDeleteMixin):
@@ -56,8 +56,8 @@ class DesignSystem(Base, TimestampMixin, SoftDeleteMixin):
            "description": self.description or "",
            "guidance": self.guidance or "",
            "parent_id": self.parent_id,
-            "created_at": self.created_at.isoformat() if self.created_at else None,
-            "updated_at": self.updated_at.isoformat() if self.updated_at else None,
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }


@@ -153,6 +153,6 @@ class DesignToken(Base, TimestampMixin, SoftDeleteMixin):
            "rationale": self.rationale,
            "supersedes": self.supersedes or [],
            "order_index": self.order_index,
-            "created_at": self.created_at.isoformat() if self.created_at else None,
-            "updated_at": self.updated_at.isoformat() if self.updated_at else None,
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }
@@ -2,7 +2,7 @@ from sqlalchemy import ForeignKey, Integer, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import TimestampMixin
+from scribe.models.base import TimestampMixin, iso


 class ForgeConnection(Base, TimestampMixin):
@@ -40,6 +40,6 @@ class ForgeConnection(Base, TimestampMixin):
            "kind": self.kind,
            "base_url": self.base_url,
            "host": self.host,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }
@@ -4,7 +4,7 @@ from sqlalchemy import ForeignKey, Integer, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, relationship

 from scribe.models import Base
-from scribe.models.base import CreatedAtMixin, TimestampMixin
+from scribe.models.base import CreatedAtMixin, TimestampMixin, iso


 class Group(Base, TimestampMixin):
@@ -27,8 +27,8 @@ class Group(Base, TimestampMixin):
            "name": self.name,
            "description": self.description,
            "created_by": self.created_by,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }


@@ -53,5 +53,5 @@ class GroupMembership(Base, CreatedAtMixin):
            "group_id": self.group_id,
            "user_id": self.user_id,
            "role": self.role,
-            "created_at": self.created_at.isoformat(),
+            "created_at": iso(self.created_at),
        }
@@ -4,9 +4,10 @@ from sqlalchemy import Boolean, DateTime, ForeignKey, Index, Text
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
+from scribe.models.base import CreatedAtMixin


-class InvitationToken(Base):
+class InvitationToken(Base, CreatedAtMixin):
    __tablename__ = "invitation_tokens"

    id: Mapped[int] = mapped_column(primary_key=True)
@@ -15,9 +16,6 @@ class InvitationToken(Base):
    invited_by: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
    used: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )

    __table_args__ = (
        Index("ix_invitation_tokens_token_hash", "token_hash"),
@@ -2,7 +2,7 @@ from sqlalchemy import ForeignKey, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import TimestampMixin, SoftDeleteMixin
+from scribe.models.base import SoftDeleteMixin, TimestampMixin, iso


 class Milestone(Base, TimestampMixin, SoftDeleteMixin):
@@ -30,6 +30,6 @@ class Milestone(Base, TimestampMixin, SoftDeleteMixin):
            "body": self.body,
            "status": self.status,
            "order_index": self.order_index,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }
@@ -6,7 +6,7 @@ from sqlalchemy.dialects.postgresql import ARRAY, JSONB
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import TimestampMixin, SoftDeleteMixin
+from scribe.models.base import SoftDeleteMixin, TimestampMixin, iso


 class TaskStatus(str, enum.Enum):
@@ -105,18 +105,14 @@ class Note(Base, TimestampMixin, SoftDeleteMixin):
            "milestone_id": self.milestone_id,
            "status": self.status,
            "priority": self.priority,
-            "due_date": self.due_date.isoformat() if self.due_date else None,
-            "started_at": self.started_at.isoformat() if self.started_at else None,
-            "completed_at": self.completed_at.isoformat() if self.completed_at else None,
+            "due_date": iso(self.due_date),
+            "started_at": iso(self.started_at),
+            "completed_at": iso(self.completed_at),
            "recurrence_rule": self.recurrence_rule,
-            "recurrence_next_spawn_at": (
-                self.recurrence_next_spawn_at.isoformat()
-                if self.recurrence_next_spawn_at
-                else None
-            ),
+            "recurrence_next_spawn_at": iso(self.recurrence_next_spawn_at),
            "is_task": self.is_task,
            "note_type": self.note_type or "note",
            "task_kind": self.task_kind,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }
@@ -2,7 +2,7 @@ from sqlalchemy import ForeignKey, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import TimestampMixin
+from scribe.models.base import TimestampMixin, iso


 class NoteDraft(Base, TimestampMixin):
@@ -25,6 +25,6 @@ class NoteDraft(Base, TimestampMixin):
            "original_body": self.original_body,
            "instruction": self.instruction,
            "scope": self.scope,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }
@@ -2,7 +2,7 @@ from sqlalchemy import ForeignKey, Index, Integer, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import CreatedAtMixin
+from scribe.models.base import CreatedAtMixin, iso


 class NoteSupersession(Base, CreatedAtMixin):
@@ -66,5 +66,5 @@ class NoteSupersession(Base, CreatedAtMixin):
            "id": self.id,
            "superseder_id": self.superseder_id,
            "superseded_id": self.superseded_id,
-            "created_at": self.created_at.isoformat() if self.created_at else None,
+            "created_at": iso(self.created_at),
        }
@@ -1,15 +1,14 @@
-from datetime import datetime, timezone
-
-from sqlalchemy import DateTime, Index, Integer, Text
+from sqlalchemy import Index, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
+from scribe.models.base import CreatedAtMixin, iso

 SURFACED = "surfaced"
 PULLED = "pulled"


-class NoteUsageEvent(Base):
+class NoteUsageEvent(Base, CreatedAtMixin):
    """One row per time a note was SURFACED to the agent, or PULLED in full.

    Answers the question RetrievalLog cannot: not "what did the ranker return
@@ -44,9 +43,6 @@ class NoteUsageEvent(Base):
    __tablename__ = "note_usage_events"

    id: Mapped[int] = mapped_column(primary_key=True)
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )
    user_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
    note_id: Mapped[int] = mapped_column(Integer, nullable=False)
    # 'surfaced' | 'pulled'
@@ -81,7 +77,7 @@ class NoteUsageEvent(Base):
    def to_dict(self) -> dict:
        return {
            "id": self.id,
-            "created_at": self.created_at.isoformat() if self.created_at else None,
+            "created_at": iso(self.created_at),
            "user_id": self.user_id,
            "note_id": self.note_id,
            "event": self.event,
@@ -2,7 +2,7 @@ from sqlalchemy import ARRAY, ForeignKey, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import CreatedAtMixin
+from scribe.models.base import CreatedAtMixin, iso


 class NoteVersion(Base, CreatedAtMixin):
@@ -26,7 +26,7 @@ class NoteVersion(Base, CreatedAtMixin):
            "tags": self.tags or [],
            "pin_kind": self.pin_kind,
            "pin_label": self.pin_label,
-            "created_at": self.created_at.isoformat(),
+            "created_at": iso(self.created_at),
        }
        if include_body:
            d["body"] = self.body
@@ -5,7 +5,7 @@ from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import CreatedAtMixin
+from scribe.models.base import CreatedAtMixin, iso


 class Notification(Base, CreatedAtMixin):
@@ -26,6 +26,6 @@ class Notification(Base, CreatedAtMixin):
            "user_id": self.user_id,
            "type": self.type,
            "payload": self.payload,
-            "read_at": self.read_at.isoformat() if self.read_at else None,
-            "created_at": self.created_at.isoformat(),
+            "read_at": iso(self.read_at),
+            "created_at": iso(self.created_at),
        }
@@ -4,9 +4,10 @@ from sqlalchemy import Boolean, DateTime, ForeignKey, Index, Text
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
+from scribe.models.base import CreatedAtMixin


-class PasswordResetToken(Base):
+class PasswordResetToken(Base, CreatedAtMixin):
    __tablename__ = "password_reset_tokens"

    id: Mapped[int] = mapped_column(primary_key=True)
@@ -14,9 +15,6 @@ class PasswordResetToken(Base):
    token_hash: Mapped[str] = mapped_column(Text, nullable=False, unique=True)
    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
    used: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )

    __table_args__ = (
        Index("ix_password_reset_tokens_token_hash", "token_hash"),
@@ -2,7 +2,7 @@ import enum
 from sqlalchemy import BigInteger, ForeignKey, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column
 from scribe.models import Base
-from scribe.models.base import TimestampMixin, SoftDeleteMixin
+from scribe.models.base import SoftDeleteMixin, TimestampMixin, iso


 class ProjectStatus(str, enum.Enum):
@@ -48,6 +48,6 @@ class Project(Base, TimestampMixin, SoftDeleteMixin):
            "color": self.color,
            "design_system_id": self.design_system_id,
            "forge_connection_id": self.forge_connection_id,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }
@@ -2,7 +2,7 @@ from sqlalchemy import ForeignKey, Integer, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import TimestampMixin
+from scribe.models.base import TimestampMixin, iso


 class RepoBinding(Base, TimestampMixin):
@@ -28,6 +28,10 @@ class RepoBinding(Base, TimestampMixin):
        Integer, ForeignKey("projects.id", ondelete="CASCADE"), nullable=False
    )
    repo_key: Mapped[str] = mapped_column(Text, nullable=False)
+    # The branch the coverage refresh reads for this binding (#2873); NULL =
+    # the forge's default branch. Chosen at bind time so a dev-first project
+    # can have its ledger follow dev instead of waiting for the merge.
+    ref: Mapped[str | None] = mapped_column(Text, nullable=True)

    def to_dict(self) -> dict:
        return {
@@ -35,6 +39,7 @@ class RepoBinding(Base, TimestampMixin):
            "user_id": self.user_id,
            "project_id": self.project_id,
            "repo_key": self.repo_key,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "ref": self.ref,
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }
@@ -5,6 +5,7 @@ from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
+from scribe.models.base import iso


 class RetrievalLog(Base):
@@ -23,6 +24,9 @@ class RetrievalLog(Base):
    __tablename__ = "retrieval_logs"

    id: Mapped[int] = mapped_column(primary_key=True)
+    # Declared here rather than via CreatedAtMixin on purpose: the composite
+    # index below orders on `created_at.desc()`, which needs the column object
+    # in this class body — a mixin's column is not in scope there.
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
    )
@@ -54,7 +58,7 @@ class RetrievalLog(Base):
    def to_dict(self) -> dict:
        return {
            "id": self.id,
-            "created_at": self.created_at.isoformat() if self.created_at else None,
+            "created_at": iso(self.created_at),
            "user_id": self.user_id,
            "source": self.source,
            "query": self.query,
@@ -4,10 +4,10 @@ from sqlalchemy import BigInteger, Boolean, Column, DateTime, ForeignKey, Index,
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import SoftDeleteMixin
+from scribe.models.base import SoftDeleteMixin, TimestampMixin, iso


-class Rulebook(Base, SoftDeleteMixin):
+class Rulebook(Base, TimestampMixin, SoftDeleteMixin):
    __tablename__ = "rulebooks"

    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
@@ -19,14 +19,6 @@ class Rulebook(Base, SoftDeleteMixin):
    always_on: Mapped[bool] = mapped_column(
        Boolean, default=False, nullable=False, server_default="false"
    )
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )
-    updated_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True),
-        default=lambda: datetime.now(timezone.utc),
-        onupdate=lambda: datetime.now(timezone.utc),
-    )

    def to_dict(self) -> dict:
        return {
@@ -35,12 +27,12 @@ class Rulebook(Base, SoftDeleteMixin):
            "title": self.title,
            "description": self.description or "",
            "always_on": self.always_on,
-            "created_at": self.created_at.isoformat() if self.created_at else None,
-            "updated_at": self.updated_at.isoformat() if self.updated_at else None,
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }


-class RulebookTopic(Base, SoftDeleteMixin):
+class RulebookTopic(Base, TimestampMixin, SoftDeleteMixin):
    __tablename__ = "rulebook_topics"
    # Partial unique: a title is unique among LIVE topics in a rulebook, so a
    # trashed topic doesn't block recreating/restoring the same title.
@@ -58,14 +50,6 @@ class RulebookTopic(Base, SoftDeleteMixin):
    title: Mapped[str] = mapped_column(Text)
    description: Mapped[str | None] = mapped_column(Text, nullable=True)
    order_index: Mapped[int] = mapped_column(Integer, default=0)
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )
-    updated_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True),
-        default=lambda: datetime.now(timezone.utc),
-        onupdate=lambda: datetime.now(timezone.utc),
-    )

    def to_dict(self) -> dict:
        return {
@@ -74,12 +58,12 @@ class RulebookTopic(Base, SoftDeleteMixin):
            "title": self.title,
            "description": self.description or "",
            "order_index": self.order_index,
-            "created_at": self.created_at.isoformat() if self.created_at else None,
-            "updated_at": self.updated_at.isoformat() if self.updated_at else None,
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }


-class Rule(Base, SoftDeleteMixin):
+class Rule(Base, TimestampMixin, SoftDeleteMixin):
    __tablename__ = "rules"
    # Partial unique: title unique among LIVE rules in a topic (soft-deleted
    # rules don't block recreating/restoring the same title).
@@ -109,14 +93,6 @@ class Rule(Base, SoftDeleteMixin):
    why: Mapped[str | None] = mapped_column(Text, nullable=True)
    how_to_apply: Mapped[str | None] = mapped_column(Text, nullable=True)
    order_index: Mapped[int] = mapped_column(Integer, default=0)
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
-    )
-    updated_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True),
-        default=lambda: datetime.now(timezone.utc),
-        onupdate=lambda: datetime.now(timezone.utc),
-    )

    def to_dict(self) -> dict:
        return {
@@ -128,8 +104,8 @@ class Rule(Base, SoftDeleteMixin):
            "why": self.why or "",
            "how_to_apply": self.how_to_apply or "",
            "order_index": self.order_index,
-            "created_at": self.created_at.isoformat() if self.created_at else None,
-            "updated_at": self.updated_at.isoformat() if self.updated_at else None,
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }


@@ -2,7 +2,7 @@ from sqlalchemy import CheckConstraint, ForeignKey, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import TimestampMixin
+from scribe.models.base import TimestampMixin, iso


 class ProjectShare(Base, TimestampMixin):
@@ -37,8 +37,8 @@ class ProjectShare(Base, TimestampMixin):
            "shared_with_group_id": self.shared_with_group_id,
            "permission": self.permission,
            "invited_by": self.invited_by,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }


@@ -74,6 +74,6 @@ class NoteShare(Base, TimestampMixin):
            "shared_with_group_id": self.shared_with_group_id,
            "permission": self.permission,
            "invited_by": self.invited_by,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }
@@ -2,7 +2,7 @@ from sqlalchemy import ForeignKey, Index, Integer, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import CreatedAtMixin, TimestampMixin, SoftDeleteMixin
+from scribe.models.base import CreatedAtMixin, SoftDeleteMixin, TimestampMixin, iso


 class System(Base, TimestampMixin, SoftDeleteMixin):
@@ -44,8 +44,8 @@ class System(Base, TimestampMixin, SoftDeleteMixin):
            "color": self.color,
            "status": self.status,
            "order_index": self.order_index,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }


@@ -2,7 +2,7 @@ from sqlalchemy import ForeignKey, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import TimestampMixin
+from scribe.models.base import TimestampMixin, iso


 class TaskLog(Base, TimestampMixin):
@@ -21,6 +21,6 @@ class TaskLog(Base, TimestampMixin):
            "user_id": self.user_id,
            "content": self.content,
            "duration_minutes": self.duration_minutes,
-            "created_at": self.created_at.isoformat(),
-            "updated_at": self.updated_at.isoformat(),
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
        }
@@ -2,7 +2,7 @@ from sqlalchemy import Index, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column

 from scribe.models import Base
-from scribe.models.base import CreatedAtMixin
+from scribe.models.base import CreatedAtMixin, iso


 class User(Base, CreatedAtMixin):
@@ -26,6 +26,6 @@ class User(Base, CreatedAtMixin):
            "username": self.username,
            "email": self.email,
            "role": self.role,
-            "created_at": self.created_at.isoformat(),
+            "created_at": iso(self.created_at),
            "has_password": self.password_hash is not None,
        }
@@ -22,6 +22,7 @@ from scribe.services.email import SMTP_SETTING_KEYS, get_base_url, get_smtp_conf
 from scribe.services.logging import get_logs, get_log_stats, log_audit
 from scribe.services.notifications import send_invitation_email
 from scribe.services.settings import (
+    SECRET_MASK,
    get_admin_setting,
    set_admin_setting,
    set_setting,
@@ -116,7 +117,7 @@ async def get_smtp():
    config = await get_smtp_config()
    # Mask password
    if config.get("smtp_password"):
-        config["smtp_password"] = "********"
+        config["smtp_password"] = SECRET_MASK
    return jsonify(config)


@@ -130,7 +131,7 @@ async def update_smtp():
    for key in SMTP_SETTING_KEYS:
        if key in data:
            # Skip password if it's the mask placeholder
-            if key == "smtp_password" and data[key] == "********":
+            if key == "smtp_password" and data[key] == SECRET_MASK:
                continue
            settings_to_save[key] = str(data[key])

@@ -157,9 +158,6 @@ async def test_smtp():
        return jsonify({"error": str(e)}), 500


-_TOKEN_MASK = "********"
-
-
 # The forge CONFIG moved to per-user keyring rows (#2778, Settings → Git
 # forges); what stays admin is the webhook secret, because the push endpoint
 # is one URL per instance and authenticates deliveries, not users.
@@ -178,7 +176,7 @@ async def get_forge_webhook_settings():
    return jsonify({
        # Secrets never leave the server — the smtp_password convention:
        # masked when set, empty when not.
-        "webhook_secret": _TOKEN_MASK if webhook_secret else "",
+        "webhook_secret": SECRET_MASK if webhook_secret else "",
    })


@@ -192,7 +190,7 @@ async def update_forge_webhook_settings():
    webhook_secret = data.get("webhook_secret")
    # The mask coming back means "unchanged" — the form round-trips what GET
    # showed it, and storing the mask would silently break the integration.
-    if webhook_secret is not None and webhook_secret != _TOKEN_MASK:
+    if webhook_secret is not None and webhook_secret != SECRET_MASK:
        await set_admin_setting(FORGE_WEBHOOK_SECRET_KEY, str(webhook_secret))
    # The secret is deliberately absent from the audit detail.
    await log_audit(
@@ -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")})
@@ -26,22 +26,6 @@ from scribe.services import dedup as dedup_svc
 from scribe.services import supersession as supersession_svc
 from scribe.services.note_usage import record_pulled

-
-async def _attach_supersession(uid: int, note_id: int, data: dict) -> None:
-    """Both directions of the supersession relation on a note payload.
-
-    Mirrors the MCP helper of the same name — the two surfaces must agree about
-    what a note's payload says, or the web UI and the agent would disagree about
-    whether a record is current.
-
-    Omitted when empty: a field that always says nothing trains readers to skip
-    fields, which is what `consolidated_at` cost (#2483).
-    """
-    rel = await supersession_svc.get_relations(uid, note_id)
-    if rel["supersedes"]:
-        data["supersedes"] = rel["supersedes"]
-    if rel["superseded_by"]:
-        data["superseded_by"] = rel["superseded_by"]
 from scribe.services.note_versions import list_versions, get_version

 logger = logging.getLogger(__name__)
@@ -142,7 +126,7 @@ async def create_note_route():
            # may not write the target. The note itself was created.
            return jsonify({"error": str(exc), "note": note.to_dict()}), 403
    out = note.to_dict()
-    await _attach_supersession(uid, note.id, out)
+    await supersession_svc.attach_relations(uid, note.id, out)
    return jsonify(out), 201


@@ -241,13 +225,17 @@ async def get_note_route(note_id: int):
    # injected line useful?" is answered by agent pulls alone, and a human
    # clicking a link would inflate exactly the number #1038 and #2085 gate on.
    record_pulled(user_id=uid, note_id=note_id, source="rest_note")
-    await _attach_supersession(uid, note_id, data)
+    await supersession_svc.attach_relations(uid, note_id, data)
    return jsonify(data)


-@notes_bp.route("/<int:note_id>", methods=["PUT"])
+@notes_bp.route("/<int:note_id>", methods=["PUT", "PATCH"])
@login_required
 async def update_note_route(note_id: int):
+    """Partial update — only the keys present in the payload change. PUT and
+    PATCH are the same handler on purpose: the form sends the field set it
+    edited, and the two verbs used to be two near-identical copies of this
+    function that drifted (one carried the supersedes contract, one did not)."""
    uid = get_current_user_id()
    # Share-aware: resolve through the ACL and write as the OWNER, so a shared
    # editor's save isn't rejected by the owner-scoped update service.
@@ -290,44 +278,10 @@ async def update_note_route(note_id: int):
        except PermissionError as exc:
            return jsonify({"error": str(exc)}), 403
    out = note.to_dict()
-    await _attach_supersession(uid, note_id, out)
+    await supersession_svc.attach_relations(uid, note_id, out)
    return jsonify(out)


-@notes_bp.route("/<int:note_id>", methods=["PATCH"])
-@login_required
-async def patch_note_route(note_id: int):
-    uid = get_current_user_id()
-    result = await get_note_for_user(uid, note_id)
-    if result is None:
-        return not_found("Note")
-    note_obj, _ = result
-    if not await can_write_note(uid, note_id):
-        return jsonify({"error": "Permission denied"}), 403
-    owner_uid = note_obj.user_id
-    data = await request.get_json()
-    fields = {}
-    for key in ("title", "body", "description", "parent_id", "project_id", "milestone_id", "status", "priority", "note_type"):
-        if key in data:
-            fields[key] = data[key]
-    if "due_date" in data:
-        if data["due_date"]:
-            result = parse_iso_date(data["due_date"], "due_date")
-            if isinstance(result, tuple):
-                return result
-            fields["due_date"] = result
-        else:
-            fields["due_date"] = None
-    if "tags" in data:
-        fields["tags"] = data["tags"]
-    try:
-        note = await update_note(owner_uid, note_id, **fields)
-    except ValueError as e:
-        return jsonify({"error": str(e)}), 400
-    if note is None:
-        return not_found("Note")
-    return jsonify(note.to_dict())
-

@notes_bp.route("/<int:note_id>", methods=["DELETE"])
@login_required
@@ -24,6 +24,35 @@ plugin_bp = Blueprint("plugin", __name__, url_prefix="/api/plugin")
 _MARKETPLACE_KEY = "plugin_marketplace_url"


+def _int_list(raw: str | None) -> list[int]:
+    """A comma-separated id list from the query string; non-ints dropped."""
+    return [int(p) for p in (raw or "").split(",") if p.strip().isdigit()]
+
+
+async def _project_scope() -> tuple[int, str, str]:
+    """(project_id, repo, unbound_repo) from the request's `project_id` /
+    `repo` query args — the one resolution every plugin endpoint shares.
+
+    An explicit project_id wins; otherwise the repo remote is resolved
+    through the caller's bindings, and a remote nobody bound comes back as
+    `unbound_repo` (normalised) so /context can say "bind this repo".
+    """
+    try:
+        project_id = int(request.args.get("project_id", 0) or 0)
+    except (TypeError, ValueError):
+        project_id = 0
+    repo = (request.args.get("repo") or "").strip()
+    unbound_repo = ""
+    if repo and not project_id:
+        resolved = await repo_bindings_svc.resolve_project(g.user.id, repo)
+        if resolved:
+            project_id = resolved
+        else:
+            unbound_repo = repo_bindings_svc.normalize_repo_key(repo)
+    return project_id, repo, unbound_repo
+
+
+
@plugin_bp.get("/context")
@login_required
 async def session_context():
@@ -37,20 +66,7 @@ async def session_context():
        project_id (optional int) — explicit override, mainly for manual/ad-hoc
            curl testing; takes precedence over `repo` when set.
    """
-    try:
-        project_id = int(request.args.get("project_id", 0) or 0)
-    except (TypeError, ValueError):
-        project_id = 0
-
-    unbound_repo = ""
-    repo = (request.args.get("repo") or "").strip()
-    if repo and not project_id:
-        resolved = await repo_bindings_svc.resolve_project(g.user.id, repo)
-        if resolved:
-            project_id = resolved
-        else:
-            unbound_repo = repo_bindings_svc.normalize_repo_key(repo)
-
+    project_id, _repo, unbound_repo = await _project_scope()
    result = await plugin_ctx_svc.build_session_context(
        g.user.id, project_id, unbound_repo=unbound_repo
    )
@@ -77,22 +93,8 @@ async def autoinject_retrieve():
                             session; skipped so each note injects at most once.
    """
    q = (request.args.get("q") or "").strip()
-    try:
-        project_id = int(request.args.get("project_id", 0) or 0)
-    except (TypeError, ValueError):
-        project_id = 0
-
-    repo = (request.args.get("repo") or "").strip()
-    if repo and not project_id:
-        resolved = await repo_bindings_svc.resolve_project(g.user.id, repo)
-        if resolved:
-            project_id = resolved
-
-    exclude_ids = [
-        int(p) for p in (request.args.get("exclude_ids") or "").split(",")
-        if p.strip().isdigit()
-    ]
-
+    project_id, _repo, _unbound = await _project_scope()
+    exclude_ids = _int_list(request.args.get("exclude_ids"))
    result = await plugin_ctx_svc.build_autoinject_hint(
        g.user.id, q, project_id=project_id, exclude_ids=exclude_ids
    )
@@ -139,25 +141,9 @@ async def write_path_prior_art():
    """
    path = (request.args.get("path") or "").strip()
    code = request.args.get("code") or ""
-    try:
-        project_id = int(request.args.get("project_id", 0) or 0)
-    except (TypeError, ValueError):
-        project_id = 0
-
-    repo = (request.args.get("repo") or "").strip()
-    if repo and not project_id:
-        resolved = await repo_bindings_svc.resolve_project(g.user.id, repo)
-        if resolved:
-            project_id = resolved
-
-    exclude_ids = [
-        int(p) for p in (request.args.get("exclude_ids") or "").split(",")
-        if p.strip().isdigit()
-    ]
-    exclude_sync_ids = [
-        int(p) for p in (request.args.get("exclude_sync_ids") or "").split(",")
-        if p.strip().isdigit()
-    ]
+    project_id, repo, _unbound = await _project_scope()
+    exclude_ids = _int_list(request.args.get("exclude_ids"))
+    exclude_sync_ids = _int_list(request.args.get("exclude_sync_ids"))
    shapes = _parse_shapes(request.args.get("shapes") or "")
    api_key = getattr(g, "api_key", None)
    may_stamp = api_key is None or getattr(api_key, "scope", "") == "write"
@@ -1,29 +1,26 @@
 """Rulebook / topic REST endpoints.

-Wraps services/rulebooks.py. Standard Scribe auth: g.user.id is the
+Wraps services/rulebooks.py. Standard Scribe auth: get_current_user_id() is the
 authenticated owner; the service enforces ownership scoping.
 """
 from __future__ import annotations

-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
 import scribe.services.rulebooks as rulebooks_svc
 from scribe.services.trash import delete as trash_delete

 rulebooks_bp = Blueprint("rulebooks", __name__, url_prefix="/api")


-def _uid() -> int:
-    return g.user.id
-

 # ── Rulebooks ───────────────────────────────────────────────────────────

@rulebooks_bp.get("/rulebooks")
@login_required
 async def list_rulebooks():
-    rows = await rulebooks_svc.list_rulebooks(_uid())
+    rows = await rulebooks_svc.list_rulebooks(get_current_user_id())
    return jsonify({"rulebooks": [rb.to_dict() for rb in rows]})


@@ -35,7 +32,7 @@ async def create_rulebook():
    if not title:
        return jsonify({"error": "title is required"}), 400
    rb = await rulebooks_svc.create_rulebook(
-        user_id=_uid(),
+        user_id=get_current_user_id(),
        title=title,
        description=data.get("description", ""),
    )
@@ -45,7 +42,7 @@ async def create_rulebook():
@rulebooks_bp.get("/rulebooks/<int:rulebook_id>")
@login_required
 async def get_rulebook(rulebook_id: int):
-    rb = await rulebooks_svc.get_rulebook(rulebook_id, _uid())
+    rb = await rulebooks_svc.get_rulebook(rulebook_id, get_current_user_id())
    if rb is None:
        return jsonify({"error": "rulebook not found"}), 404
    return jsonify(rb.to_dict())
@@ -56,7 +53,7 @@ async def get_rulebook(rulebook_id: int):
 async def update_rulebook(rulebook_id: int):
    data = await request.get_json() or {}
    fields = {k: v for k, v in data.items() if k in ("title", "description", "always_on")}
-    rb = await rulebooks_svc.update_rulebook(rulebook_id, _uid(), **fields)
+    rb = await rulebooks_svc.update_rulebook(rulebook_id, get_current_user_id(), **fields)
    if rb is None:
        return jsonify({"error": "rulebook not found"}), 404
    return jsonify(rb.to_dict())
@@ -65,7 +62,7 @@ async def update_rulebook(rulebook_id: int):
@rulebooks_bp.delete("/rulebooks/<int:rulebook_id>")
@login_required
 async def delete_rulebook(rulebook_id: int):
-    await trash_delete(_uid(), "rulebook", rulebook_id)
+    await trash_delete(get_current_user_id(), "rulebook", rulebook_id)
    return "", 204


@@ -75,7 +72,7 @@ async def delete_rulebook(rulebook_id: int):
@login_required
 async def list_topics(rulebook_id: int):
    try:
-        rows = await rulebooks_svc.list_topics(rulebook_id, _uid())
+        rows = await rulebooks_svc.list_topics(rulebook_id, get_current_user_id())
    except ValueError as exc:
        return jsonify({"error": str(exc)}), 404
    return jsonify({"topics": [t.to_dict() for t in rows]})
@@ -91,7 +88,7 @@ async def create_topic(rulebook_id: int):
    try:
        topic = await rulebooks_svc.create_topic(
            rulebook_id=rulebook_id,
-            user_id=_uid(),
+            user_id=get_current_user_id(),
            title=title,
            description=data.get("description", ""),
            order_index=data.get("order_index", 0),
@@ -109,7 +106,7 @@ async def update_topic(topic_id: int):
        k: v for k, v in data.items()
        if k in ("title", "description", "order_index")
    }
-    topic = await rulebooks_svc.update_topic(topic_id, _uid(), **fields)
+    topic = await rulebooks_svc.update_topic(topic_id, get_current_user_id(), **fields)
    if topic is None:
        return jsonify({"error": "topic not found"}), 404
    return jsonify(topic.to_dict())
@@ -118,7 +115,7 @@ async def update_topic(topic_id: int):
@rulebooks_bp.delete("/rulebook-topics/<int:topic_id>")
@login_required
 async def delete_topic(topic_id: int):
-    if await trash_delete(_uid(), "topic", topic_id) is None:
+    if await trash_delete(get_current_user_id(), "topic", topic_id) is None:
        return jsonify({"error": "topic not found"}), 404
    return "", 204

@@ -140,7 +137,7 @@ async def list_rules():
        return jsonify({"error": "rulebook_id, topic_id, project_id must be integers"}), 400

    rows = await rulebooks_svc.list_rules(
-        user_id=_uid(),
+        user_id=get_current_user_id(),
        rulebook_id=rulebook_id,
        topic_id=topic_id,
        project_id=project_id,
@@ -159,7 +156,7 @@ async def create_rule(topic_id: int):
    try:
        rule = await rulebooks_svc.create_rule(
            topic_id=topic_id,
-            user_id=_uid(),
+            user_id=get_current_user_id(),
            title=title,
            statement=statement,
            why=data.get("why", ""),
@@ -174,7 +171,7 @@ async def create_rule(topic_id: int):
@rulebooks_bp.get("/rules/<int:rule_id>")
@login_required
 async def get_rule(rule_id: int):
-    rule = await rulebooks_svc.get_rule(rule_id, _uid())
+    rule = await rulebooks_svc.get_rule(rule_id, get_current_user_id())
    if rule is None:
        return jsonify({"error": "rule not found"}), 404
    return jsonify(rule.to_dict())
@@ -188,7 +185,7 @@ async def update_rule(rule_id: int):
        k: v for k, v in data.items()
        if k in ("title", "statement", "why", "how_to_apply", "order_index")
    }
-    rule = await rulebooks_svc.update_rule(rule_id, _uid(), **fields)
+    rule = await rulebooks_svc.update_rule(rule_id, get_current_user_id(), **fields)
    if rule is None:
        return jsonify({"error": "rule not found"}), 404
    return jsonify(rule.to_dict())
@@ -197,7 +194,7 @@ async def update_rule(rule_id: int):
@rulebooks_bp.delete("/rules/<int:rule_id>")
@login_required
 async def delete_rule(rule_id: int):
-    if await trash_delete(_uid(), "rule", rule_id) is None:
+    if await trash_delete(get_current_user_id(), "rule", rule_id) is None:
        return jsonify({"error": "rule not found"}), 404
    return "", 204

@@ -213,7 +210,7 @@ async def subscribe_project(project_id: int):
        return jsonify({"error": "rulebook_id is required"}), 400
    try:
        await rulebooks_svc.subscribe_project(
-            project_id=project_id, rulebook_id=int(rulebook_id), user_id=_uid(),
+            project_id=project_id, rulebook_id=int(rulebook_id), user_id=get_current_user_id(),
        )
    except ValueError as exc:
        return jsonify({"error": str(exc)}), 404
@@ -227,7 +224,7 @@ async def subscribe_project(project_id: int):
 async def unsubscribe_project(project_id: int, rulebook_id: int):
    try:
        await rulebooks_svc.unsubscribe_project(
-            project_id=project_id, rulebook_id=rulebook_id, user_id=_uid(),
+            project_id=project_id, rulebook_id=rulebook_id, user_id=get_current_user_id(),
        )
    except ValueError as exc:
        return jsonify({"error": str(exc)}), 404
@@ -238,7 +235,7 @@ async def unsubscribe_project(project_id: int, rulebook_id: int):
@login_required
 async def get_project_rules(project_id: int):
    result = await rulebooks_svc.get_applicable_rules(
-        project_id=project_id, user_id=_uid(),
+        project_id=project_id, user_id=get_current_user_id(),
    )
    return jsonify(result)

@@ -248,7 +245,7 @@ async def get_project_rules(project_id: int):
 async def suppress_project_rule(project_id: int, rule_id: int):
    try:
        await rulebooks_svc.suppress_rule_for_project(
-            project_id=project_id, rule_id=rule_id, user_id=_uid(),
+            project_id=project_id, rule_id=rule_id, user_id=get_current_user_id(),
        )
    except ValueError as exc:
        return jsonify({"error": str(exc)}), 404
@@ -260,7 +257,7 @@ async def suppress_project_rule(project_id: int, rule_id: int):
 async def unsuppress_project_rule(project_id: int, rule_id: int):
    try:
        await rulebooks_svc.unsuppress_rule_for_project(
-            project_id=project_id, rule_id=rule_id, user_id=_uid(),
+            project_id=project_id, rule_id=rule_id, user_id=get_current_user_id(),
        )
    except ValueError as exc:
        return jsonify({"error": str(exc)}), 404
@@ -272,7 +269,7 @@ async def unsuppress_project_rule(project_id: int, rule_id: int):
 async def suppress_project_topic(project_id: int, topic_id: int):
    try:
        await rulebooks_svc.suppress_topic_for_project(
-            project_id=project_id, topic_id=topic_id, user_id=_uid(),
+            project_id=project_id, topic_id=topic_id, user_id=get_current_user_id(),
        )
    except ValueError as exc:
        return jsonify({"error": str(exc)}), 404
@@ -284,7 +281,7 @@ async def suppress_project_topic(project_id: int, topic_id: int):
 async def unsuppress_project_topic(project_id: int, topic_id: int):
    try:
        await rulebooks_svc.unsuppress_topic_for_project(
-            project_id=project_id, topic_id=topic_id, user_id=_uid(),
+            project_id=project_id, topic_id=topic_id, user_id=get_current_user_id(),
        )
    except ValueError as exc:
        return jsonify({"error": str(exc)}), 404
@@ -303,7 +300,7 @@ async def create_project_rule(project_id: int):
    try:
        rule = await rulebooks_svc.create_project_rule(
            project_id=project_id,
-            user_id=_uid(),
+            user_id=get_current_user_id(),
            title=title,
            statement=statement,
            why=data.get("why", ""),
@@ -9,7 +9,9 @@ from quart import Blueprint, jsonify, request

 from scribe.auth import login_required, get_current_user_id
 from scribe.config import Config
-from scribe.services.settings import delete_setting, get_all_settings, get_setting, set_settings_batch
+from scribe.services.settings import (
+    SECRET_MASK, delete_setting, get_all_settings, get_setting, set_settings_batch,
+)

 logger = logging.getLogger(__name__)

@@ -22,12 +24,11 @@ settings_bp = Blueprint("settings", __name__, url_prefix="/api/settings")
 # rows live on the admin's own user_id, so the plain GET returned them raw.
 # (forge_token left with 0078: forge credentials are keyring rows now, #2778.)
 _SECRET_KEYS = frozenset({"smtp_password", "forge_webhook_secret"})
-_SECRET_MASK = "********"


 def _masked(settings: dict) -> dict:
    return {
-        k: (_SECRET_MASK if k in _SECRET_KEYS and v else v)
+        k: (SECRET_MASK if k in _SECRET_KEYS and v else v)
        for k, v in settings.items()
    }

@@ -53,7 +54,7 @@ async def update_settings_route():
        str_v = str(v)
        # A masked secret round-tripping through a client is "unchanged", not
        # a request to store the mask over the real credential.
-        if k in _SECRET_KEYS and str_v == _SECRET_MASK:
+        if k in _SECRET_KEYS and str_v == SECRET_MASK:
            continue
        if not str_v:
            await delete_setting(uid, k)
@@ -127,7 +128,7 @@ async def update_forge_connection_route(connection_id: int):
    token = str(data.get("token", ""))
    # The mask coming back means "unchanged" — the form round-trips what the
    # list showed, and storing the mask would silently break the connection.
-    if token == _SECRET_MASK:
+    if token == SECRET_MASK:
        token = ""
    try:
        row = await update_connection(
@@ -1,33 +1,30 @@
 """Trash REST API — list / restore / purge soft-deleted content by batch."""
 from __future__ import annotations

-from quart import Blueprint, g, jsonify
+from quart import Blueprint, jsonify

-from scribe.auth import login_required
+from scribe.auth import get_current_user_id, login_required
 import scribe.services.trash as trash_svc

 trash_bp = Blueprint("trash", __name__, url_prefix="/api/trash")


-def _uid() -> int:
-    return g.user.id
-

@trash_bp.get("")
@login_required
 async def list_trash():
-    return jsonify({"batches": await trash_svc.list_trash(_uid())})
+    return jsonify({"batches": await trash_svc.list_trash(get_current_user_id())})


@trash_bp.post("/<batch_id>/restore")
@login_required
 async def restore_batch(batch_id: str):
-    n = await trash_svc.restore(_uid(), batch_id)
+    n = await trash_svc.restore(get_current_user_id(), batch_id)
    return jsonify({"restored": n})


@trash_bp.delete("/<batch_id>")
@login_required
 async def purge_batch(batch_id: str):
-    n = await trash_svc.purge(_uid(), batch_id)
+    n = await trash_svc.purge(get_current_user_id(), batch_id)
    return jsonify({"purged": n})
@@ -13,8 +13,11 @@ def generate_key() -> str:
    return "fmcp_" + secrets.token_urlsafe(32)


-def _hash_key(key: str) -> str:
-    return hashlib.sha256(key.encode()).hexdigest()
+def hash_token(raw: str) -> str:
+    """The ONE fingerprint for every bearer secret stored by hash — API keys,
+    password-reset tokens, invitation tokens. Stored rows hold this, never
+    the raw value; a lookup hashes the presented token and compares."""
+    return hashlib.sha256(raw.encode()).hexdigest()


 def _key_prefix(key: str) -> str:
@@ -32,7 +35,7 @@ async def create_api_key(
    key = ApiKey(
        user_id=user_id,
        name=name,
-        key_hash=_hash_key(full_key),
+        key_hash=hash_token(full_key),
        key_prefix=_key_prefix(full_key),
        scope=scope,
    )
@@ -70,7 +73,7 @@ async def revoke_api_key(user_id: int, key_id: int) -> bool:

 async def lookup_key(raw_key: str) -> ApiKey | None:
    """Look up a non-revoked ApiKey by raw token value. Updates last_used_at."""
-    key_hash = _hash_key(raw_key)
+    key_hash = hash_token(raw_key)
    async with async_session() as session:
        result = await session.execute(
            select(ApiKey).where(
@@ -1,4 +1,3 @@
-import hashlib
 import logging
 import secrets
 from datetime import datetime, timedelta, timezone
@@ -12,6 +11,8 @@ from scribe.models.invitation import InvitationToken
 from scribe.models.password_reset import PasswordResetToken
 from scribe.models.setting import Setting
 from scribe.models.user import User
+from scribe.services.api_keys import hash_token
+from scribe.services.settings import get_admin_setting

 logger = logging.getLogger(__name__)

@@ -142,16 +143,7 @@ async def is_registration_open() -> bool:
    user_count = await get_user_count()
    if user_count == 0:
        return True
-
-    async with async_session() as session:
-        # Find the admin user's registration_open setting
-        result = await session.execute(
-            select(Setting)
-            .join(User, Setting.user_id == User.id)
-            .where(User.role == "admin", Setting.key == "registration_open")
-        )
-        setting = result.scalar_one_or_none()
-        return setting.value == "true" if setting else False
+    return await get_admin_setting("registration_open", "false") == "true"


 async def list_users() -> list[User]:
@@ -211,7 +203,7 @@ async def get_user_by_email(email: str) -> User | None:
 async def create_password_reset_token(user_id: int) -> str:
    """Generate a password reset token. Returns the raw token (for the email link)."""
    raw_token = secrets.token_urlsafe(32)
-    token_hash = hashlib.sha256(raw_token.encode()).hexdigest()
+    token_hash = hash_token(raw_token)
    expires_at = datetime.now(timezone.utc) + timedelta(hours=1)

    async with async_session() as session:
@@ -239,7 +231,7 @@ async def create_password_reset_token(user_id: int) -> str:

 async def reset_password_with_token(raw_token: str, new_password: str) -> int | None:
    """Validate a reset token and update the user's password. Returns user_id on success."""
-    token_hash = hashlib.sha256(raw_token.encode()).hexdigest()
+    token_hash = hash_token(raw_token)

    async with async_session() as session:
        result = await session.execute(
@@ -270,7 +262,7 @@ async def reset_password_with_token(raw_token: str, new_password: str) -> int |
 async def create_invitation(email: str, invited_by: int) -> str:
    """Generate an invitation token. Returns the raw token (for the email link)."""
    raw_token = secrets.token_urlsafe(32)
-    token_hash = hashlib.sha256(raw_token.encode()).hexdigest()
+    token_hash = hash_token(raw_token)
    expires_at = datetime.now(timezone.utc) + timedelta(days=7)

    async with async_session() as session:
@@ -299,7 +291,7 @@ async def create_invitation(email: str, invited_by: int) -> str:

 async def validate_invitation_token(raw_token: str) -> InvitationToken | None:
    """Look up by hash, check not used/expired. Returns the token record with email."""
-    token_hash = hashlib.sha256(raw_token.encode()).hexdigest()
+    token_hash = hash_token(raw_token)

    async with async_session() as session:
        result = await session.execute(
@@ -319,7 +311,7 @@ async def validate_invitation_token(raw_token: str) -> InvitationToken | None:

 async def register_with_invitation(raw_token: str, username: str, password: str) -> User | None:
    """Validate token, create user with the invitation's email, mark token used."""
-    token_hash = hashlib.sha256(raw_token.encode()).hexdigest()
+    token_hash = hash_token(raw_token)

    async with async_session() as session:
        result = await session.execute(
@@ -398,20 +390,16 @@ async def purge_expired_auth_tokens(grace_days: int = 7) -> int:
    return removed


-async def _auth_token_retention_loop() -> None:
-    import asyncio
-    while True:
-        await asyncio.sleep(86400)  # daily
-        try:
-            removed = await purge_expired_auth_tokens()
-            if removed:
-                logger.info("Auth token retention: deleted %d expired token(s)", removed)
-        except Exception:
-            logger.exception("Error in auth token retention cleanup")
+async def _auth_token_retention_tick() -> None:
+    removed = await purge_expired_auth_tokens()
+    if removed:
+        logger.info("Auth token retention: deleted %d expired token(s)", removed)


 def start_auth_token_retention_loop() -> None:
    global _auth_retention_task
-    import asyncio
    if _auth_retention_task is None or _auth_retention_task.done():
-        _auth_retention_task = asyncio.create_task(_auth_token_retention_loop())
+        from scribe.services.background import start_periodic
+        _auth_retention_task = start_periodic(
+            86400, _auth_token_retention_tick, label="auth_token_retention",  # daily
+        )
@@ -45,6 +45,26 @@ def spawn(coro: Coroutine, *, site: str) -> None:
    task.add_done_callback(_done)


+def start_periodic(interval_s: float, work, *, label: str) -> asyncio.Task:
+    """A forever loop that sleeps ``interval_s`` then awaits ``work()``, logging
+    (never raising) when a tick fails — the one shape the hourly/daily
+    retention sweeps share (log retention, notification sweep, auth-token
+    purge). Sleeps FIRST so startup isn't a sweep; holds a strong reference
+    like spawn() so the loop cannot be garbage-collected mid-flight."""
+    async def _loop() -> None:
+        while True:
+            await asyncio.sleep(interval_s)
+            try:
+                await work()
+            except Exception:
+                logger.exception("periodic task %s failed", label)
+
+    task = asyncio.get_running_loop().create_task(_loop(), name=f"periodic-{label}")
+    _pending.add(task)
+    task.add_done_callback(_pending.discard)
+    return task
+
+
 async def drain() -> None:
    """Await everything in flight — for tests that need the writes landed."""
    while _pending:
@@ -11,7 +11,7 @@ from scribe.models.note_supersession import NoteSupersession
 from scribe.models.note_version import NoteVersion
 from scribe.models.design_system import DesignSystem, DesignToken
 from scribe.models.note_usage import NoteUsageEvent
-from scribe.models.code_shape import CodeShape, CodeShapeEvent
+from scribe.models.code_shape import CodeShape, CodeShapeEvent, CodeShapeUse
 from scribe.models.project import Project
 from scribe.models.repo_binding import RepoBinding
 from scribe.models.rulebook import (
@@ -42,8 +42,11 @@ logger = logging.getLogger(__name__)
 # snippet target survives the id re-mapping, else the row rejoins the todo.
 # v8 (2026-08) added code_shape_events — the ledger's history (#2793): what
 # was used where, when, and why is not recomputable, so it travels.
+# 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.
 # Bump when the serialized schema changes.
-BACKUP_VERSION = 8
+BACKUP_VERSION = 9

 # 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
@@ -62,7 +65,7 @@ _BACKED_UP = [
    "systems", "record_systems", "design_systems", "design_tokens",
    "note_usage_events", "repo_bindings", "note_supersessions",
    # v7 (2026-08): the shape ledger (#2787); v8: its history (#2793).
-    "code_shapes", "code_shape_events",
+    "code_shapes", "code_shape_events", "code_shape_uses",
 ]

 # Tables intentionally NOT in the backup, surfaced in the payload so the gap is
@@ -182,6 +185,10 @@ def _code_shape_event_rows(rows) -> list[dict]:
    return [r.to_dict() for r in rows]


+def _code_shape_use_rows(rows) -> list[dict]:
+    return [r.to_dict() for r in rows]
+
+
 def _repo_binding_rows(rows) -> list[dict]:
    return [
        {"user_id": r.user_id, "project_id": r.project_id, "repo_key": r.repo_key}
@@ -189,6 +196,142 @@ def _repo_binding_rows(rows) -> list[dict]:
    ]


+# Row builders for the sections both exporters carry. Pure, like the join-table
+# helpers above; the full and per-user exports used to restate every one of
+# these comprehensions side by side, and a column added to one and not the
+# other is a backup that silently drops it (#2293's shape, one layer down).
+
+def _user_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": u.id, "username": u.username, "email": u.email,
+            "password_hash": u.password_hash, "oauth_sub": u.oauth_sub,
+            "role": u.role, "session_version": u.session_version,
+            "created_at": u.created_at.isoformat(),
+        }
+        for u in rows
+    ]
+
+
+def _project_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": p.id, "user_id": p.user_id, "title": p.title,
+            "description": p.description, "goal": p.goal, "status": p.status,
+            "color": p.color,
+            "created_at": p.created_at.isoformat(),
+            "updated_at": p.updated_at.isoformat(),
+        }
+        for p in rows
+    ]
+
+
+def _milestone_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": m.id, "user_id": m.user_id, "project_id": m.project_id,
+            "title": m.title, "description": m.description, "status": m.status,
+            "order_index": m.order_index,
+            "created_at": m.created_at.isoformat(),
+            "updated_at": m.updated_at.isoformat(),
+        }
+        for m in rows
+    ]
+
+
+def _note_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": n.id, "user_id": n.user_id, "title": n.title, "body": n.body,
+            "tags": n.tags or [], "parent_id": n.parent_id,
+            "project_id": n.project_id, "milestone_id": n.milestone_id,
+            "status": n.status, "priority": n.priority,
+            "due_date": n.due_date.isoformat() if n.due_date else None,
+            "created_at": n.created_at.isoformat(),
+            "updated_at": n.updated_at.isoformat(),
+        }
+        for n in rows
+    ]
+
+
+def _task_log_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": tl.id, "user_id": tl.user_id, "task_id": tl.task_id,
+            "content": tl.content, "duration_minutes": tl.duration_minutes,
+            "created_at": tl.created_at.isoformat(),
+            "updated_at": tl.updated_at.isoformat(),
+        }
+        for tl in rows
+    ]
+
+
+def _note_draft_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": nd.id, "user_id": nd.user_id, "note_id": nd.note_id,
+            "proposed_body": nd.proposed_body, "original_body": nd.original_body,
+            "instruction": nd.instruction, "scope": nd.scope,
+            "created_at": nd.created_at.isoformat(),
+            "updated_at": nd.updated_at.isoformat(),
+        }
+        for nd in rows
+    ]
+
+
+def _note_version_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": nv.id, "user_id": nv.user_id, "note_id": nv.note_id,
+            "title": nv.title, "body": nv.body, "tags": nv.tags or [],
+            "pin_kind": nv.pin_kind, "pin_label": nv.pin_label,
+            "created_at": nv.created_at.isoformat(),
+        }
+        for nv in rows
+    ]
+
+
+def _setting_rows(rows) -> list[dict]:
+    return [{"user_id": s.user_id, "key": s.key, "value": s.value} for s in rows]
+
+
+def _rulebook_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": rb.id, "owner_user_id": rb.owner_user_id, "title": rb.title,
+            "description": rb.description, "always_on": rb.always_on,
+            "created_at": rb.created_at.isoformat(),
+            "updated_at": rb.updated_at.isoformat(),
+        }
+        for rb in rows
+    ]
+
+
+def _topic_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": t.id, "rulebook_id": t.rulebook_id, "title": t.title,
+            "description": t.description, "order_index": t.order_index,
+            "created_at": t.created_at.isoformat(),
+            "updated_at": t.updated_at.isoformat(),
+        }
+        for t in rows
+    ]
+
+
+def _rule_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": r.id, "topic_id": r.topic_id, "project_id": r.project_id,
+            "title": r.title, "statement": r.statement, "why": r.why,
+            "how_to_apply": r.how_to_apply, "order_index": r.order_index,
+            "created_at": r.created_at.isoformat(),
+            "updated_at": r.updated_at.isoformat(),
+        }
+        for r in rows
+    ]
+
+
 # ---------------------------------------------------------------------------
 # Export
 # ---------------------------------------------------------------------------
@@ -225,6 +368,9 @@ async def export_full_backup() -> dict:
        code_shape_events = (await session.execute(
            select(CodeShapeEvent).order_by(CodeShapeEvent.at, CodeShapeEvent.id)
        )).scalars().all()
+        code_shape_uses = (await session.execute(
+            select(CodeShapeUse).order_by(CodeShapeUse.shape_id, CodeShapeUse.snippet_id)
+        )).scalars().all()
        rulebooks = (await session.execute(select(Rulebook))).scalars().all()
        topics = (await session.execute(select(RulebookTopic))).scalars().all()
        rules = (await session.execute(select(Rule))).scalars().all()
@@ -247,148 +393,17 @@ async def export_full_backup() -> dict:
            "Store it securely and restrict access."
        ),
        "_not_included": _NOT_INCLUDED,
-        "users": [
-            {
-                "id": u.id,
-                "username": u.username,
-                "email": u.email,
-                "password_hash": u.password_hash,
-                "oauth_sub": u.oauth_sub,
-                "role": u.role,
-                "session_version": u.session_version,
-                "created_at": u.created_at.isoformat(),
-            }
-            for u in users
-        ],
-        "projects": [
-            {
-                "id": p.id,
-                "user_id": p.user_id,
-                "title": p.title,
-                "description": p.description,
-                "goal": p.goal,
-                "status": p.status,
-                "color": p.color,
-                "created_at": p.created_at.isoformat(),
-                "updated_at": p.updated_at.isoformat(),
-            }
-            for p in projects
-        ],
-        "milestones": [
-            {
-                "id": m.id,
-                "user_id": m.user_id,
-                "project_id": m.project_id,
-                "title": m.title,
-                "description": m.description,
-                "status": m.status,
-                "order_index": m.order_index,
-                "created_at": m.created_at.isoformat(),
-                "updated_at": m.updated_at.isoformat(),
-            }
-            for m in milestones
-        ],
-        "notes": [
-            {
-                "id": n.id,
-                "user_id": n.user_id,
-                "title": n.title,
-                "body": n.body,
-                "tags": n.tags or [],
-                "parent_id": n.parent_id,
-                "project_id": n.project_id,
-                "milestone_id": n.milestone_id,
-                "status": n.status,
-                "priority": n.priority,
-                "due_date": n.due_date.isoformat() if n.due_date else None,
-                "created_at": n.created_at.isoformat(),
-                "updated_at": n.updated_at.isoformat(),
-            }
-            for n in notes
-        ],
-        "task_logs": [
-            {
-                "id": tl.id,
-                "user_id": tl.user_id,
-                "task_id": tl.task_id,
-                "content": tl.content,
-                "duration_minutes": tl.duration_minutes,
-                "created_at": tl.created_at.isoformat(),
-                "updated_at": tl.updated_at.isoformat(),
-            }
-            for tl in task_logs
-        ],
-        "note_drafts": [
-            {
-                "id": nd.id,
-                "user_id": nd.user_id,
-                "note_id": nd.note_id,
-                "proposed_body": nd.proposed_body,
-                "original_body": nd.original_body,
-                "instruction": nd.instruction,
-                "scope": nd.scope,
-                "created_at": nd.created_at.isoformat(),
-                "updated_at": nd.updated_at.isoformat(),
-            }
-            for nd in note_drafts
-        ],
-        "note_versions": [
-            {
-                "id": nv.id,
-                "user_id": nv.user_id,
-                "note_id": nv.note_id,
-                "title": nv.title,
-                "body": nv.body,
-                "tags": nv.tags or [],
-                "pin_kind": nv.pin_kind,
-                "pin_label": nv.pin_label,
-                "created_at": nv.created_at.isoformat(),
-            }
-            for nv in note_versions
-        ],
-        "settings": [
-            {"user_id": s.user_id, "key": s.key, "value": s.value}
-            for s in settings
-        ],
-        "rulebooks": [
-            {
-                "id": rb.id,
-                "owner_user_id": rb.owner_user_id,
-                "title": rb.title,
-                "description": rb.description,
-                "always_on": rb.always_on,
-                "created_at": rb.created_at.isoformat(),
-                "updated_at": rb.updated_at.isoformat(),
-            }
-            for rb in rulebooks
-        ],
-        "rulebook_topics": [
-            {
-                "id": t.id,
-                "rulebook_id": t.rulebook_id,
-                "title": t.title,
-                "description": t.description,
-                "order_index": t.order_index,
-                "created_at": t.created_at.isoformat(),
-                "updated_at": t.updated_at.isoformat(),
-            }
-            for t in topics
-        ],
-        "rules": [
-            {
-                "id": r.id,
-                "topic_id": r.topic_id,
-                "project_id": r.project_id,
-                "title": r.title,
-                "statement": r.statement,
-                "why": r.why,
-                "how_to_apply": r.how_to_apply,
-                "order_index": r.order_index,
-                "created_at": r.created_at.isoformat(),
-                "updated_at": r.updated_at.isoformat(),
-            }
-            for r in rules
-        ],
+        "users": _user_rows(users),
+        "projects": _project_rows(projects),
+        "milestones": _milestone_rows(milestones),
+        "notes": _note_rows(notes),
+        "task_logs": _task_log_rows(task_logs),
+        "note_drafts": _note_draft_rows(note_drafts),
+        "note_versions": _note_version_rows(note_versions),
+        "settings": _setting_rows(settings),
+        "rulebooks": _rulebook_rows(rulebooks),
+        "rulebook_topics": _topic_rows(topics),
+        "rules": _rule_rows(rules),
        "rulebook_subscriptions": _subscription_rows(subscriptions),
        "rule_suppressions": _rule_suppression_rows(rule_suppressions),
        "topic_suppressions": _topic_suppression_rows(topic_suppressions),
@@ -401,6 +416,7 @@ async def export_full_backup() -> dict:
        "note_supersessions": _note_supersession_rows(supersessions),
        "code_shapes": _code_shape_rows(code_shapes),
        "code_shape_events": _code_shape_event_rows(code_shape_events),
+        "code_shape_uses": _code_shape_use_rows(code_shape_uses),
    }


@@ -477,6 +493,11 @@ async def export_user_backup(user_id: int) -> dict:
            select(CodeShapeEvent).where(CodeShapeEvent.project_id.in_(project_ids))
            .order_by(CodeShapeEvent.at, CodeShapeEvent.id)
        )).scalars().all() if project_ids else []
+        code_shape_uses = (await session.execute(
+            select(CodeShapeUse).join(CodeShape, CodeShape.id == CodeShapeUse.shape_id)
+            .where(CodeShape.project_id.in_(project_ids))
+            .order_by(CodeShapeUse.shape_id, CodeShapeUse.snippet_id)
+        )).scalars().all() if project_ids else []
        rulebooks = (await session.execute(
            select(Rulebook).where(Rulebook.owner_user_id == user_id)
        )).scalars().all()
@@ -526,135 +547,16 @@ async def export_user_backup(user_id: int) -> dict:
            "role": user.role,
            "created_at": user.created_at.isoformat(),
        } if user else None,
-        "projects": [
-            {
-                "id": p.id,
-                "user_id": p.user_id,
-                "title": p.title,
-                "description": p.description,
-                "goal": p.goal,
-                "status": p.status,
-                "color": p.color,
-                "created_at": p.created_at.isoformat(),
-                "updated_at": p.updated_at.isoformat(),
-            }
-            for p in projects
-        ],
-        "milestones": [
-            {
-                "id": m.id,
-                "user_id": m.user_id,
-                "project_id": m.project_id,
-                "title": m.title,
-                "description": m.description,
-                "status": m.status,
-                "order_index": m.order_index,
-                "created_at": m.created_at.isoformat(),
-                "updated_at": m.updated_at.isoformat(),
-            }
-            for m in milestones
-        ],
-        "notes": [
-            {
-                "id": n.id,
-                "user_id": n.user_id,
-                "title": n.title,
-                "body": n.body,
-                "tags": n.tags or [],
-                "parent_id": n.parent_id,
-                "project_id": n.project_id,
-                "milestone_id": n.milestone_id,
-                "status": n.status,
-                "priority": n.priority,
-                "due_date": n.due_date.isoformat() if n.due_date else None,
-                "created_at": n.created_at.isoformat(),
-                "updated_at": n.updated_at.isoformat(),
-            }
-            for n in notes
-        ],
-        "task_logs": [
-            {
-                "id": tl.id,
-                "user_id": tl.user_id,
-                "task_id": tl.task_id,
-                "content": tl.content,
-                "duration_minutes": tl.duration_minutes,
-                "created_at": tl.created_at.isoformat(),
-                "updated_at": tl.updated_at.isoformat(),
-            }
-            for tl in task_logs
-        ],
-        "note_drafts": [
-            {
-                "id": nd.id,
-                "user_id": nd.user_id,
-                "note_id": nd.note_id,
-                "proposed_body": nd.proposed_body,
-                "original_body": nd.original_body,
-                "instruction": nd.instruction,
-                "scope": nd.scope,
-                "created_at": nd.created_at.isoformat(),
-                "updated_at": nd.updated_at.isoformat(),
-            }
-            for nd in note_drafts
-        ],
-        "note_versions": [
-            {
-                "id": nv.id,
-                "user_id": nv.user_id,
-                "note_id": nv.note_id,
-                "title": nv.title,
-                "body": nv.body,
-                "tags": nv.tags or [],
-                "pin_kind": nv.pin_kind,
-                "pin_label": nv.pin_label,
-                "created_at": nv.created_at.isoformat(),
-            }
-            for nv in note_versions
-        ],
-        "settings": [
-            {"user_id": s.user_id, "key": s.key, "value": s.value}
-            for s in settings
-        ],
-        "rulebooks": [
-            {
-                "id": rb.id,
-                "owner_user_id": rb.owner_user_id,
-                "title": rb.title,
-                "description": rb.description,
-                "always_on": rb.always_on,
-                "created_at": rb.created_at.isoformat(),
-                "updated_at": rb.updated_at.isoformat(),
-            }
-            for rb in rulebooks
-        ],
-        "rulebook_topics": [
-            {
-                "id": t.id,
-                "rulebook_id": t.rulebook_id,
-                "title": t.title,
-                "description": t.description,
-                "order_index": t.order_index,
-                "created_at": t.created_at.isoformat(),
-                "updated_at": t.updated_at.isoformat(),
-            }
-            for t in topics
-        ],
-        "rules": [
-            {
-                "id": r.id,
-                "topic_id": r.topic_id,
-                "project_id": r.project_id,
-                "title": r.title,
-                "statement": r.statement,
-                "why": r.why,
-                "how_to_apply": r.how_to_apply,
-                "order_index": r.order_index,
-                "created_at": r.created_at.isoformat(),
-                "updated_at": r.updated_at.isoformat(),
-            }
-            for r in rules
-        ],
+        "projects": _project_rows(projects),
+        "milestones": _milestone_rows(milestones),
+        "notes": _note_rows(notes),
+        "task_logs": _task_log_rows(task_logs),
+        "note_drafts": _note_draft_rows(note_drafts),
+        "note_versions": _note_version_rows(note_versions),
+        "settings": _setting_rows(settings),
+        "rulebooks": _rulebook_rows(rulebooks),
+        "rulebook_topics": _topic_rows(topics),
+        "rules": _rule_rows(rules),
        "rulebook_subscriptions": _subscription_rows(subscriptions),
        "rule_suppressions": _rule_suppression_rows(rule_suppressions),
        "topic_suppressions": _topic_suppression_rows(topic_suppressions),
@@ -667,6 +569,7 @@ async def export_user_backup(user_id: int) -> dict:
        "note_supersessions": _note_supersession_rows(supersessions),
        "code_shapes": _code_shape_rows(code_shapes),
        "code_shape_events": _code_shape_event_rows(code_shape_events),
+        "code_shape_uses": _code_shape_use_rows(code_shape_uses),
    }


@@ -771,6 +674,7 @@ async def _restore_v2(data: dict) -> dict:
        "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,
+        "code_shape_uses": 0,
    }

    async with async_session() as session:
@@ -1219,6 +1123,20 @@ async def _restore_v2(data: dict) -> dict:
            ))
            stats["code_shape_events"] += 1

+        # v9: consumption edges (#2870) ride their shape AND their snippet —
+        # both ends must have survived, or the edge is no longer a fact.
+        for use in data.get("code_shape_uses", []):
+            new_shape_id = shape_id_map.get(use.get("shape_id") or 0)
+            new_sid = note_id_map.get(use.get("snippet_id") or 0)
+            if new_shape_id is None or new_sid is None:
+                continue
+            session.add(CodeShapeUse(
+                shape_id=new_shape_id, snippet_id=new_sid,
+                basis=use.get("basis", "import"), evidence=use.get("evidence"),
+                created_at=_dt(use.get("created_at")),
+            ))
+            stats["code_shape_uses"] += 1
+
        await session.commit()

    logger.info("Restored v2/v3 backup: %s", stats)
@@ -36,7 +36,7 @@ from typing import NamedTuple
 from datetime import datetime, timedelta, timezone

 from scribe.services.forge import ForgeSelector, get_forges
-from scribe.services.repo_bindings import keys_for_project
+from scribe.services.repo_bindings import bindings_for_project
 from scribe.services.settings import get_setting, set_setting

 logger = logging.getLogger(__name__)
@@ -107,6 +107,7 @@ class Definition(NamedTuple):
    signature: str
    body_sha: str
    body: str
+    line: int = -1   # 0-based line the definition starts on (#2869)


 def _definition_on(raw: str) -> tuple[str, str] | None:
@@ -184,13 +185,56 @@ def extract_definitions(text: str) -> list[Definition]:
                end = j
                break
        block = lines[i:end]
+        # A CSS rule's fingerprint is its DECLARATIONS, not its selector
+        # (#2872): the row's identity already carries the selector, and the
+        # question the fingerprint answers for derive grouping is "is this the
+        # same rule under another name?" — .closed-msg / .error-block /
+        # .success-msg with identical bodies are one dup group, not three
+        # lonely rows. Sym blocks keep their signature line in the hash.
+        hashed = block[1:] if kind == "css" and len(block) > 1 else block
        out.append(Definition(
-            kind, name, lines[i].strip()[:_SIGNATURE_CAP], _block_sha(block),
-            "\n".join(block),
+            kind, name, lines[i].strip()[:_SIGNATURE_CAP], _block_sha(hashed),
+            "\n".join(block), i,
        ))
    return out


+# --- by-construction scope (#2869) -------------------------------------------
+#
+# A Vue single-file component's `<style scoped>` rules and its `<script setup>`
+# functions cannot be reached from any other file: they are one-offs by
+# construction, not by judgment. The sync stamps them `scoped` (mechanical) so
+# the human todo holds only shapes a person should look at, while the bodies
+# stay in play for the proposer, derive grouping and divergence — the five
+# auth views' identical rules were found exactly there. Unscoped `<style>` in
+# a .vue and every non-.vue file stay ordinary.
+_STYLE_OPEN_RE = re.compile(r"^\s*<style\b[^>]*\bscoped\b", re.IGNORECASE)
+_STYLE_CLOSE_RE = re.compile(r"^\s*</style\s*>", re.IGNORECASE)
+
+
+def scoped_definitions(path: str, text: str, defs: list[Definition]) -> set[tuple[str, str]]:
+    """The (kind, name) pairs among ``defs`` that are one-offs by
+    construction in this file: every sym in a .vue, and every css rule
+    that starts inside a `<style scoped>` block. Empty for other files."""
+    if not (path or "").lower().endswith(".vue"):
+        return set()
+    ranges: list[tuple[int, int]] = []
+    open_at: int | None = None
+    for i, ln in enumerate(text.splitlines()):
+        if open_at is None and _STYLE_OPEN_RE.match(ln):
+            open_at = i
+        elif open_at is not None and _STYLE_CLOSE_RE.match(ln):
+            ranges.append((open_at, i))
+            open_at = None
+    out: set[tuple[str, str]] = set()
+    for d in defs:
+        if d.kind == "sym":
+            out.add((d.kind, d.name))
+        elif any(a <= d.line <= b for a, b in ranges):
+            out.add((d.kind, d.name))
+    return out
+
+
 def extract_shapes(text: str) -> list[tuple[str, str]]:
    """Every (kind, name) this text DEFINES — kind is "css" or "sym".

@@ -220,6 +264,7 @@ class ArchiveShape(NamedTuple):
    signature: str
    body_sha: str
    body: str
+    scoped: bool = False   # one-off by construction (#2869)


 def shapes_from_archive(blob: bytes) -> list[tuple[str, str, str]]:
@@ -250,9 +295,14 @@ def definitions_from_archive(blob: bytes) -> list[ArchiveShape]:
                text = handle.read().decode("utf-8")
            except UnicodeDecodeError:
                continue
+            defs = extract_definitions(text)
+            scoped = scoped_definitions(path, text, defs)
            shapes.extend(
-                ArchiveShape(path, d.kind, d.name, d.signature, d.body_sha, d.body)
-                for d in extract_definitions(text)
+                ArchiveShape(
+                    path, d.kind, d.name, d.signature, d.body_sha, d.body,
+                    (d.kind, d.name) in scoped,
+                )
+                for d in defs
            )
    return shapes

@@ -357,12 +407,15 @@ async def compute_coverage(
    # the project's repos (#2792).
    canons = None
    proposer_stats = {"examined": 0, "proposed": 0, "semantic_checked": 0}
-    for key in await keys_for_project(user_id, project_id):
+    for binding in await bindings_for_project(user_id, project_id):
+        key = binding.repo_key
        hit = selector.resolve(key)
        if hit is None:
            continue  # bound to a host no connection serves
        forge, api_repo = hit
-        ref = await forge.default_branch(api_repo)
+        # The binding's own ref when it names one (#2873: a dev-first project
+        # has its ledger follow dev), else the forge's default branch.
+        ref = binding.ref or await forge.default_branch(api_repo)
        definitions = definitions_from_archive(await forge.archive(api_repo, ref))
        # The head commit is provenance sugar on the ledger rows; failing to
        # learn it must not fail the sync — the ref names the point well
@@ -414,7 +467,7 @@ async def compute_coverage(
    # repo that was unreachable today still has live rows, and they count.
    rows = await shape_ledger.live_rows(project_id)
    counts = {"canonical": 0, "instance": 0, "variant": 0, "exempt": 0,
-              "unclassified": 0}
+              "scoped": 0, "unclassified": 0}
    for row in rows:
        counts[row.status] = counts.get(row.status, 0) + 1
    by_repo: dict[str, dict[str, int]] = {}
@@ -435,6 +488,7 @@ async def compute_coverage(
        # confirm, the largest derive-first groups, and what this refresh did.
        "proposed": proposals["proposed"],
        "derive_groups": proposals["derive_groups"],
+        "top_canon": proposals.get("top_canon"),
        "proposer": proposer_stats,
        # The divergence readout (#2793): button B where button A is canon,
        # and judged shapes whose bodies moved since they were judged.
@@ -571,7 +625,7 @@ def coverage_line(coverage: dict) -> str:
    counts = coverage.get("counts") or {}
    breakdown = " · ".join(
        f"{counts[k]} {k}"
-        for k in ("canonical", "instance", "variant", "exempt")
+        for k in ("canonical", "instance", "variant", "exempt", "scoped")
        if counts.get(k)
    )
    line = (
@@ -592,6 +646,14 @@ def coverage_line(coverage: dict) -> str:
            standing.append(f"{n_groups} derive group{'s' if n_groups != 1 else ''}")
        if coverage.get("divergent"):
            standing.append(f"{coverage['divergent']} DIVERGENT")
+        # The next action, on the line (#2874): the canon with the biggest
+        # queue to confirm, and the widest body-identical copy to consolidate.
+        top = coverage.get("top_canon") or {}
+        if top.get("snippet_id"):
+            standing.append(f"top canon #{top['snippet_id']} ×{top.get('count', 0)}")
+        first = (coverage.get("derive_groups") or [{}])[0]
+        if first.get("label") and first.get("files"):
+            standing.append(f"top copy {first['label']} ×{first['files']} files")
        if standing:
            line += f" ({', '.join(standing)})"
        gaps = [g["dir"] for g in coverage.get("largest_gaps") or []]
@@ -15,6 +15,7 @@ from scribe.models import async_session
 from scribe.models.note import Note
 from scribe.models.project import Project
 from scribe.models.milestone import Milestone
+from scribe.models.base import iso
 from scribe.services import milestones as milestones_svc

 logger = logging.getLogger(__name__)
@@ -173,7 +174,7 @@ async def _recently_completed(user_id: int) -> list[dict]:
            .order_by(Note.completed_at.desc()).limit(RECENT_DONE_LIMIT)
        )).all()
        return [{"id": n.id, "title": n.title, "project_title": ptitle,
-                 "completed_at": n.completed_at.isoformat()} for n, ptitle in rows]
+                 "completed_at": iso(n.completed_at)} for n, ptitle in rows]


 async def _week_stats(user_id: int) -> dict:
@@ -21,6 +21,7 @@ from datetime import datetime, timezone
 from sqlalchemy import text

 from scribe.models import async_session, engine
+from scribe.models.base import iso
 from scribe.services.settings import get_admin_setting, set_admin_setting

 logger = logging.getLogger(__name__)
@@ -128,10 +129,6 @@ _HEALTH_SQL = text("""
 """)


-def _iso(value) -> str | None:
-    return value.isoformat() if value is not None else None
-
-
 async def get_table_health() -> dict:
    """Per-table health from Postgres statistics + the total database size.

@@ -156,8 +153,8 @@ async def get_table_health() -> dict:
            "dead_pct": float(r["dead_pct"] or 0),
            "total_bytes": int(r["total_bytes"] or 0),
            "mod_since_analyze": int(r["mod_since_analyze"] or 0),
-            "last_vacuum": _iso(r["last_vacuum"]),
-            "last_analyze": _iso(r["last_analyze"]),
+            "last_vacuum": iso(r["last_vacuum"]),
+            "last_analyze": iso(r["last_analyze"]),
        }
        for r in rows
    ]
@@ -1,9 +1,8 @@
 """Daily APScheduler cron for basic DB maintenance (targeted VACUUM ANALYZE).

-Mirrors trash_scheduler.py: a single global BackgroundScheduler job bridges
-into the asyncio loop to run the async maintenance. Scheduled for 04:00 UTC by
-default — after the 03:30 trash purge — so it collects the dead tuples that
-night's delete sweeps leave behind.
+One ScheduledJob (services/scheduler.py). Scheduled for 04:00 UTC by default
+— after the 03:30 trash purge — so it collects the dead tuples that night's
+delete sweeps leave behind.

 Two things are operator-tunable from the admin Settings card:
  - db_maintenance_enabled ("true"/"false") — checked at fire time, so toggling
@@ -16,9 +15,9 @@ from __future__ import annotations
 import asyncio
 import logging

-from apscheduler.schedulers.background import BackgroundScheduler
 from apscheduler.triggers.cron import CronTrigger

+from scribe.services.scheduler import ScheduledJob
 from scribe.services.settings import get_admin_setting

 logger = logging.getLogger(__name__)
@@ -26,9 +25,6 @@ logger = logging.getLogger(__name__)
 _JOB_ID = "db_maintenance_vacuum"
 _DEFAULT_HOUR = 4

-_scheduler: BackgroundScheduler | None = None
-_loop: asyncio.AbstractEventLoop | None = None
-

 async def get_maintenance_hour() -> int:
    """The configured run-hour (UTC, 0–23), clamped; default 04:00."""
@@ -45,23 +41,20 @@ async def is_maintenance_enabled() -> bool:
    return (await get_admin_setting("db_maintenance_enabled", "true")) != "false"


-def _run_maintenance_threadsafe() -> None:
-    """APScheduler invokes this from a worker thread; bridge into the loop."""
-    if _loop is None:
-        logger.warning("db maintenance scheduler: no loop registered")
+async def _run_maintenance() -> None:
+    if not await is_maintenance_enabled():
+        logger.debug("db maintenance: disabled, skipping scheduled run")
        return
+    from scribe.services.db_maintenance import run_maintenance
+    await run_maintenance()

-    async def _runner():
-        try:
-            if not await is_maintenance_enabled():
-                logger.debug("db maintenance: disabled, skipping scheduled run")
-                return
-            from scribe.services.db_maintenance import run_maintenance
-            await run_maintenance()
-        except Exception:
-            logger.exception("db maintenance run failed")

-    asyncio.run_coroutine_threadsafe(_runner(), _loop)
+_JOB = ScheduledJob(_JOB_ID, _run_maintenance, label="DB maintenance")
+
+
+def _trigger(hour: int) -> CronTrigger:
+    hour = hour if 0 <= hour <= 23 else _DEFAULT_HOUR
+    return CronTrigger(hour=hour, minute=0, timezone="UTC")


 def start_db_maintenance_scheduler(
@@ -72,36 +65,15 @@ def start_db_maintenance_scheduler(
    in rather than read here so we never block the event loop at startup. The
    job's enabled-gate is re-checked at every fire, so only the hour is needed
    up front."""
-    global _scheduler, _loop
-    if _scheduler is not None:
-        return
-    _loop = loop
    hour = hour if 0 <= hour <= 23 else _DEFAULT_HOUR
-    _scheduler = BackgroundScheduler()
-    _scheduler.add_job(
-        _run_maintenance_threadsafe,
-        trigger=CronTrigger(hour=hour, minute=0, timezone="UTC"),
-        id=_JOB_ID,
-        replace_existing=True,
-    )
-    _scheduler.start()
-    logger.info("DB maintenance scheduler started (daily %02d:00 UTC)", hour)
+    _JOB.start(loop, _trigger(hour), describe=f"daily {hour:02d}:00 UTC")


 def reschedule_db_maintenance(hour: int) -> None:
    """Move the live job to a new UTC hour (called when the admin changes it)."""
-    if _scheduler is None:
-        return
    hour = hour if 0 <= hour <= 23 else _DEFAULT_HOUR
-    _scheduler.reschedule_job(
-        _JOB_ID, trigger=CronTrigger(hour=hour, minute=0, timezone="UTC")
-    )
-    logger.info("DB maintenance scheduler rescheduled to %02d:00 UTC", hour)
+    _JOB.reschedule(_trigger(hour), describe=f"{hour:02d}:00 UTC")


 def stop_db_maintenance_scheduler() -> None:
-    global _scheduler
-    if _scheduler is not None:
-        _scheduler.shutdown(wait=False)
-        _scheduler = None
-        logger.info("DB maintenance scheduler stopped")
+    _JOB.stop()
@@ -32,6 +32,7 @@ from scribe.models import async_session
 from scribe.models.embedding import NoteEmbedding
 from scribe.models.note import Note
 from scribe.models.rulebook import Rule
+from scribe.models.base import iso
 from scribe.services import embeddings as embeddings_svc
 # Imported rather than redeclared: no service imports this module (the create
 # gate is called from the routes/tools layer), so there is no cycle to dodge,
@@ -592,8 +593,8 @@ async def find_duplicate_records(
                titles[int(i)] = t
                records[int(i)] = d or {}
                meta[int(i)] = {
-                    "created_at": created.isoformat() if created else None,
-                    "updated_at": updated.isoformat() if updated else None,
+                    "created_at": iso(created),
+                    "updated_at": iso(updated),
                    "task_kind": task_kind,
                }
    except Exception:
@@ -16,12 +16,14 @@ endorsed, so a one-off direct share has to be searched for rather than arriving
 in your ambient lists.
 """
 import json
+import re
 import logging

 from sqlalchemy import and_, func, or_, select

 from scribe.models import async_session
 from scribe.models.note import Note
+from scribe.models.base import iso
 from scribe.services.access import browsable_notes_clause, readable_notes_clause

 logger = logging.getLogger(__name__)
@@ -75,6 +77,10 @@ def location_matches(data: dict | None, parts: dict[str, str]) -> bool:
        if all(
            _path_matches((loc.get(key) or "").strip(), want)
            if key == "path"
+            # Repo names are recorded free-form ("Scribe" / "FabledScribe" /
+            # "fabledscribe") — case is never the distinguishing thing (#2874).
+            else (loc.get(key) or "").strip().lower() == want.lower()
+            if key == "repo"
            else (loc.get(key) or "").strip() == want
            for key, want in parts.items()
        ):
@@ -98,6 +104,11 @@ def location_jsonpath(parts: dict[str, str]) -> str:
        if key == "path":
            prefix = json.dumps(want.rstrip("/") + "/")
            filters.append(f"(@.path == {literal} || @.path starts with {prefix})")
+        elif key == "repo":
+            # Case-insensitive, anchored, regex-escaped (#2874) — mirrors the
+            # Python dialect's .lower() compare.
+            pattern = json.dumps("^" + re.escape(want) + "$")
+            filters.append(f'(@.repo like_regex {pattern} flag "i")')
        else:
            filters.append(f"@.{key} == {literal}")
    return f"$.locations[*] ? ({' && '.join(filters)})"
@@ -211,8 +222,8 @@ def _note_to_item(note: Note) -> dict:
        # These lists now include records shared with the caller, so the client
        # needs the owner to tell "mine" from "someone else's" in a mixed list.
        "user_id": note.user_id,
-        "created_at": note.created_at.isoformat(),
-        "updated_at": note.updated_at.isoformat(),
+        "created_at": iso(note.created_at),
+        "updated_at": iso(note.updated_at),
    }
    # Drift verdict (#2086), when one has been recorded. Included here rather
    # than decorated on by the snippet layer because `current` is derivable from
@@ -249,7 +260,7 @@ def _note_to_item(note: Note) -> dict:
        item["task_kind"] = note.task_kind
        item["status"] = note.status
        item["priority"] = note.priority
-        item["due_date"] = note.due_date.isoformat() if note.due_date else None
+        item["due_date"] = iso(note.due_date)

    return item

@@ -194,18 +194,14 @@ async def delete_old_logs(retention_days: int) -> int:
        return result.rowcount


-async def _retention_loop() -> None:
-    while True:
-        await asyncio.sleep(3600)  # hourly
-        try:
-            deleted = await delete_old_logs(Config.LOG_RETENTION_DAYS)
-            if deleted:
-                logger.info("Log retention: deleted %d old log entries", deleted)
-        except Exception:
-            logger.exception("Error in log retention cleanup")
+async def _retention_tick() -> None:
+    deleted = await delete_old_logs(Config.LOG_RETENTION_DAYS)
+    if deleted:
+        logger.info("Log retention: deleted %d old log entries", deleted)


 def start_log_retention_loop() -> None:
    global _retention_task
    if _retention_task is None or _retention_task.done():
-        _retention_task = asyncio.create_task(_retention_loop())
+        from scribe.services.background import start_periodic
+        _retention_task = start_periodic(3600, _retention_tick, label="log_retention")  # hourly
@@ -235,12 +235,6 @@ async def get_project_milestone_summaries(


 async def get_project_milestone_summary(user_id: int, project_id: int) -> list[dict]:
-    """Return ordered list of milestones with their progress stats."""
-    milestones = await list_milestones(user_id, project_id)
-    result = []
-    for m in milestones:
-        progress = await get_milestone_progress(m.id)
-        entry = m.to_dict()
-        entry.update(progress)
-        result.append(entry)
-    return result
+    """Ordered milestones with progress — the one-project view of
+    get_project_milestone_summaries (two queries, not N+1)."""
+    return (await get_project_milestone_summaries(user_id, [project_id])).get(project_id, [])
@@ -36,6 +36,7 @@ from sqlalchemy import case, func, select

 from scribe.models import async_session
 from scribe.models.note_usage import PULLED, SURFACED, NoteUsageEvent
+from scribe.models.base import iso

 logger = logging.getLogger(__name__)

@@ -232,13 +233,13 @@ async def usage_for_notes(note_ids: list[int]) -> dict[int, dict]:
            slot["ambient_count"] = int(n)
        elif event == SURFACED:
            slot["surfaced_count"] = int(n)
-            slot["last_surfaced_at"] = last_at.isoformat() if last_at else None
+            slot["last_surfaced_at"] = iso(last_at)
        elif event == PULLED:
            # Pulls are pulls regardless of what surfaced the record — the
            # question a pull answers ("did anyone ever open this?") doesn't
            # depend on how it was found.
            slot["pull_count"] = slot["pull_count"] + int(n)
-            latest = last_at.isoformat() if last_at else None
+            latest = iso(last_at)
            if latest and (slot["last_pulled_at"] or "") < latest:
                slot["last_pulled_at"] = latest
    return out
@@ -3,17 +3,20 @@
 import asyncio
 import json
 import logging
-from datetime import date, datetime, time, timezone
+from datetime import date, datetime, time, timedelta, timezone

-from sqlalchemy import func, select, text
+from sqlalchemy import delete as sa_delete, func, select, text
+from sqlalchemy import update as sa_update

 from scribe.models import async_session
 from scribe.models.app_log import AppLog
 from scribe.models.note import Note
-from scribe.models.setting import Setting
+from scribe.models.notification import Notification
 from scribe.models.user import User
+from scribe.models.base import iso
 from scribe.services.email import _email_html, is_smtp_configured, send_email
 from scribe.services.logging import log_audit
+from scribe.services.settings import get_setting

 logger = logging.getLogger(__name__)

@@ -29,13 +32,7 @@ SECURITY_EVENT_LABELS = {

 async def _get_user_notification_pref(user_id: int, key: str) -> bool:
    """Check if a user has a notification preference enabled (default True)."""
-    async with async_session() as session:
-        result = await session.execute(
-            select(Setting).where(Setting.user_id == user_id, Setting.key == key)
-        )
-        setting = result.scalar_one_or_none()
-        # Default to enabled
-        return setting.value != "false" if setting else True
+    return await get_setting(user_id, key, "true") != "false"


 async def _get_user_email(user_id: int) -> str | None:
@@ -222,7 +219,7 @@ async def check_due_tasks() -> None:
                for task in user_tasks:
                    overdue = task.due_date < today if task.due_date else False
                    date_color = "#ef4444" if overdue else "#374151"
-                    date_label = f'<span style="color: {date_color};">{task.due_date.isoformat()}</span>' if task.due_date else ""
+                    date_label = f'<span style="color: {date_color};">{iso(task.due_date)}</span>' if task.due_date else ""
                    overdue_badge = ' <span style="color:#ef4444;font-weight:600;font-size:11px;">(overdue)</span>' if overdue else ""
                    task_rows += (
                        f'<tr>'
@@ -261,13 +258,10 @@ _NOTIFICATION_RETENTION_DAYS = 30

 async def purge_old_read_notifications(retention_days: int = _NOTIFICATION_RETENTION_DAYS) -> int:
    """Delete already-read in-app notifications older than retention_days."""
-    from datetime import timedelta
-    from sqlalchemy import delete
-    from scribe.models.notification import Notification
    cutoff = datetime.now(timezone.utc) - timedelta(days=retention_days)
    async with async_session() as session:
        result = await session.execute(
-            delete(Notification).where(
+            sa_delete(Notification).where(
                Notification.read_at.isnot(None),
                Notification.read_at < cutoff,
            )
@@ -276,25 +270,21 @@ async def purge_old_read_notifications(retention_days: int = _NOTIFICATION_RETEN
        return result.rowcount or 0


-async def _notification_loop() -> None:
-    while True:
-        await asyncio.sleep(3600)  # hourly
-        try:
-            await check_due_tasks()
-        except Exception:
-            logger.exception("Error in notification loop")
-        try:
-            removed = await purge_old_read_notifications()
-            if removed:
-                logger.info("Notification retention: deleted %d read notification(s)", removed)
-        except Exception:
-            logger.exception("Error in notification retention cleanup")
+async def _notification_tick() -> None:
+    try:
+        await check_due_tasks()
+    except Exception:
+        logger.exception("Error in notification loop")
+    removed = await purge_old_read_notifications()
+    if removed:
+        logger.info("Notification retention: deleted %d read notification(s)", removed)


 def start_notification_loop() -> None:
    global _notification_task
    if _notification_task is None or _notification_task.done():
-        _notification_task = asyncio.create_task(_notification_loop())
+        from scribe.services.background import start_periodic
+        _notification_task = start_periodic(3600, _notification_tick, label="notifications")  # hourly


 # ---------------------------------------------------------------------------
@@ -303,7 +293,6 @@ def start_notification_loop() -> None:

 async def create_in_app_notification(user_id: int, notif_type: str, payload: dict):
    """Create an in-app Notification record."""
-    from scribe.models.notification import Notification
    async with async_session() as session:
        n = Notification(user_id=user_id, type=notif_type, payload=payload)
        session.add(n)
@@ -316,11 +305,10 @@ async def _fire_share_email(user_id: int, subject: str, body_text: str) -> None:
    try:
        if not await is_smtp_configured():
            return
-        async with async_session() as session:
-            user = await session.get(User, user_id)
-        if user and user.email:
+        email = await _get_user_email(user_id)
+        if email:
            html = _email_html(subject, f"<p>{body_text.replace(chr(10), '<br>')}</p>")
-            await send_email(user.email, subject, html)
+            await send_email(email, subject, html)
    except Exception:
        logger.exception("Share email notification failed for user %d", user_id)

@@ -427,7 +415,6 @@ async def notify_group_added(


 async def list_in_app_notifications(user_id: int, unread_only: bool = True) -> list[dict]:
-    from scribe.models.notification import Notification
    async with async_session() as session:
        q = select(Notification).where(Notification.user_id == user_id)
        if unread_only:
@@ -438,7 +425,6 @@ async def list_in_app_notifications(user_id: int, unread_only: bool = True) -> l


 async def unread_notification_count(user_id: int) -> int:
-    from scribe.models.notification import Notification
    async with async_session() as session:
        result = await session.execute(
            select(func.count()).where(
@@ -450,8 +436,6 @@ async def unread_notification_count(user_id: int) -> int:


 async def mark_notification_read(user_id: int, notification_id: int) -> bool:
-    from scribe.models.notification import Notification
-    from datetime import timezone as tz
    async with async_session() as session:
        n = (await session.execute(
            select(Notification).where(
@@ -461,21 +445,17 @@ async def mark_notification_read(user_id: int, notification_id: int) -> bool:
        )).scalar_one_or_none()
        if not n:
            return False
-        from datetime import datetime
-        n.read_at = datetime.now(tz.utc)
+        n.read_at = datetime.now(timezone.utc)
        await session.commit()
        return True


 async def mark_all_notifications_read(user_id: int) -> int:
-    from scribe.models.notification import Notification
-    from datetime import datetime, timezone as tz
-    from sqlalchemy import update as sa_update
    async with async_session() as session:
        result = await session.execute(
            sa_update(Notification)
            .where(Notification.user_id == user_id, Notification.read_at.is_(None))
-            .values(read_at=datetime.now(tz.utc))
+            .values(read_at=datetime.now(timezone.utc))
            .returning(Notification.id)
        )
        await session.commit()
@@ -60,12 +60,7 @@ async def start_planning(user_id: int, project_id: int, title: str) -> dict:

    return {
        "milestone": milestone.to_dict(),
-        "applicable_rules": applicable["rules"],
-        "subscribed_rulebooks": applicable["subscribed_rulebooks"],
-        "applicable_rules_truncated": applicable["truncated"],
-        "project_rules": applicable.get("project_rules", []),
-        "suppressed_rules": applicable.get("suppressed_rules", []),
-        "suppressed_topics": applicable.get("suppressed_topics", []),
+        **rulebooks_svc.rules_payload(applicable),
        "project_goal": getattr(project, "goal", "") or "",
        "open_task_count": open_count,
    }
@@ -208,54 +208,9 @@ async def get_project_summaries(


 async def get_project_summary(user_id: int, project_id: int) -> dict:
-    """Return task counts by status, note count, and last activity."""
-    async with async_session() as session:
-        # Task counts by status
-        task_rows = await session.execute(
-            select(Note.status, func.count(Note.id))
-            .where(
-                Note.user_id == user_id,
-                Note.project_id == project_id,
-                Note.status.isnot(None),
-                Note.deleted_at.is_(None),
-            )
-            .group_by(Note.status)
-        )
-        # Initialise all three lifecycle keys to 0 so consumers can sum them
-        # safely without `?? 0` guards. Frontend interface declares all three
-        # as required; rendering `undefined + N` yields NaN.
-        task_counts: dict[str, int] = {"todo": 0, "in_progress": 0, "done": 0}
-        for status, count in task_rows.fetchall():
-            task_counts[status] = count
-
-        # Note count (non-tasks)
-        note_count_result = await session.scalar(
-            select(func.count(Note.id)).where(
-                Note.user_id == user_id,
-                Note.project_id == project_id,
-                Note.status.is_(None),
-                Note.deleted_at.is_(None),
-            )
-        )
-        note_count = note_count_result or 0
-
-        # Last activity
-        last_activity_result = await session.scalar(
-            select(func.max(Note.updated_at)).where(
-                Note.user_id == user_id,
-                Note.project_id == project_id,
-            )
-        )
-
-        from scribe.services.milestones import get_project_milestone_summary
-        milestone_summary = await get_project_milestone_summary(user_id, project_id)
-
-        return {
-            "task_counts": task_counts,
-            "note_count": note_count,
-            "last_activity": last_activity_result.isoformat() if last_activity_result else None,
-            "milestone_summary": milestone_summary,
-        }
+    """Return task counts by status, note count, and last activity — the
+    one-project view of get_project_summaries (one rule, not two copies)."""
+    return (await get_project_summaries(user_id, [project_id]))[project_id]


 # ---------------------------------------------------------------------------
@@ -279,8 +234,6 @@ async def list_projects_for_user(user_id: int, status: str | None = None) -> lis
    """Owned projects + shared projects, each dict has 'permission' field."""
    from scribe.models.group import GroupMembership
    from scribe.models.share import ProjectShare
-    from scribe.services.access import PERMISSION_RANK
-
    owned = await list_projects(user_id, status)
    owned_ids = {p.id for p in owned}

@@ -307,13 +260,14 @@ async def list_projects_for_user(user_id: int, status: str | None = None) -> lis
                )
            )).scalars().all()

-    seen: dict[int, str] = {}
-    for share in list(shared_direct) + list(shared_group):
-        if share.project_id in owned_ids:
-            continue
-        prev = seen.get(share.project_id)
-        if prev is None or PERMISSION_RANK[share.permission] > PERMISSION_RANK[prev]:
-            seen[share.project_id] = share.permission
+    from scribe.services.sharing import best_permission_by
+    seen = {
+        pid: perm
+        for pid, perm in best_permission_by(
+            list(shared_direct) + list(shared_group), "project_id"
+        ).items()
+        if pid not in owned_ids
+    }

    for pid, perm in seen.items():
        if status:
@@ -4,7 +4,7 @@ Every 15 minutes, creates the next occurrence of any recurring task whose spawn
 time has arrived — draining `recurrence_next_spawn_at`, which is armed on task
 completion. Without this job, recurring tasks would never recur.

-Uses the BackgroundScheduler pattern shared with the other *_scheduler modules.
+One ScheduledJob (services/scheduler.py), like the other *_scheduler modules.
 (Formerly event_scheduler.py, which also ran event reminders + CalDAV sync;
 those were removed when the calendar surface was retired.)
 """
@@ -13,52 +13,27 @@ from __future__ import annotations
 import asyncio
 import logging

-from apscheduler.schedulers.background import BackgroundScheduler
 from apscheduler.triggers.interval import IntervalTrigger

-logger = logging.getLogger(__name__)
+from scribe.services.scheduler import ScheduledJob

-_scheduler: BackgroundScheduler | None = None
-_loop: asyncio.AbstractEventLoop | None = None
+logger = logging.getLogger(__name__)


 async def _run_recurrence_spawn() -> None:
    from scribe.services.recurrence import spawn_recurring_tasks  # noqa: PLC0415
-    try:
-        await spawn_recurring_tasks()
-    except Exception:
-        logger.warning("Recurring-task spawn job failed", exc_info=True)
+    await spawn_recurring_tasks()


-def _run_recurrence_spawn_threadsafe(loop: asyncio.AbstractEventLoop) -> None:
-    asyncio.run_coroutine_threadsafe(_run_recurrence_spawn(), loop)
+_JOB = ScheduledJob("recurrence_spawn", _run_recurrence_spawn, label="Recurring-task spawn")


 def start_recurrence_scheduler(loop: asyncio.AbstractEventLoop) -> None:
-    global _scheduler, _loop
-    if _scheduler is not None:
-        return
-    _loop = loop
-    _scheduler = BackgroundScheduler()
-
    # Spawn the next occurrence of due recurring tasks every 15 minutes.
    # Without this job, recurrence_next_spawn_at is armed on completion but
    # never drained, so recurring tasks never recur.
-    _scheduler.add_job(
-        _run_recurrence_spawn_threadsafe,
-        trigger=IntervalTrigger(minutes=15),
-        args=[loop],
-        id="recurrence_spawn",
-        replace_existing=True,
-    )
-
-    _scheduler.start()
-    logger.info("Recurrence scheduler started (recurring-task spawn every 15m)")
+    _JOB.start(loop, IntervalTrigger(minutes=15), describe="recurring-task spawn every 15m")


 def stop_recurrence_scheduler() -> None:
-    global _scheduler
-    if _scheduler is not None:
-        _scheduler.shutdown(wait=False)
-        _scheduler = None
-        logger.info("Recurrence scheduler stopped")
+    _JOB.stop()
@@ -68,8 +68,16 @@ async def resolve_project(user_id: int, raw_repo: str) -> int | None:
        return row.scalar_one_or_none()


-async def set_binding(user_id: int, raw_repo: str, project_id: int) -> RepoBinding:
-    """Create or update the binding for a repo. Idempotent on (user, repo_key)."""
+async def set_binding(
+    user_id: int, raw_repo: str, project_id: int, ref: str | None = None,
+) -> RepoBinding:
+    """Create or update the binding for a repo. Idempotent on (user, repo_key).
+
+    ``ref`` (#2873) is the branch the coverage refresh reads for this
+    binding: a name sets it, ``""`` clears it back to the forge's default
+    branch, ``None`` leaves whatever stands (a re-bind that only moves the
+    project keeps the ref it had).
+    """
    key = normalize_repo_key(raw_repo)
    if not key:
        raise ValueError("repo remote is empty or unparseable")
@@ -85,6 +93,8 @@ async def set_binding(user_id: int, raw_repo: str, project_id: int) -> RepoBindi
            session.add(binding)
        else:
            binding.project_id = project_id
+        if ref is not None:
+            binding.ref = ref.strip() or None
        await session.commit()
        await session.refresh(binding)
        return binding
@@ -100,6 +110,18 @@ async def list_bindings(user_id: int) -> list[RepoBinding]:
        return list(rows.scalars().all())


+async def bindings_for_project(user_id: int, project_id: int) -> list[RepoBinding]:
+    """Every binding of a project — key AND the ref its ledger follows (#2873)."""
+    async with async_session() as session:
+        rows = await session.execute(
+            select(RepoBinding).where(
+                RepoBinding.user_id == user_id,
+                RepoBinding.project_id == project_id,
+            ).order_by(RepoBinding.repo_key)
+        )
+        return list(rows.scalars().all())
+
+
 async def keys_for_project(user_id: int, project_id: int) -> list[str]:
    """Every repo key bound to a project — the snippet→forge join (#2691).

@@ -779,3 +779,22 @@ async def get_applicable_rules(
        "truncated": truncated,
        "subscribed_rulebooks": subscribed_rulebooks,
    }
+
+
+def rules_payload(applicable: dict) -> dict:
+    """The caller-facing shape of a get_applicable_rules() result.
+
+    Every surface that hands rules to an agent (enter_project, get_project,
+    get_milestone, get_task for legacy plans, start_planning) carries the
+    same six keys under the same names — so a reader learns them once. One
+    place renames `rules` → `applicable_rules` and `truncated` →
+    `applicable_rules_truncated`; the tools merge this into their payloads.
+    """
+    return {
+        "applicable_rules": applicable["rules"],
+        "applicable_rules_truncated": applicable["truncated"],
+        "subscribed_rulebooks": applicable["subscribed_rulebooks"],
+        "project_rules": applicable.get("project_rules", []),
+        "suppressed_rules": applicable.get("suppressed_rules", []),
+        "suppressed_topics": applicable.get("suppressed_topics", []),
+    }
@@ -0,0 +1,78 @@
+"""One APScheduler job bridged into the asyncio loop — the shape the four
+*_scheduler modules (recurrence spawn, auto-pin scan, trash purge, DB
+maintenance) each used to carry a private copy of.
+
+APScheduler's BackgroundScheduler fires from a worker thread; the work is
+async and must run on the app's loop, so the fire is bridged with
+``run_coroutine_threadsafe``. Each job is a module-level singleton: start is
+idempotent, stop shuts the scheduler down, and a job whose trigger the
+operator can change (the maintenance hour) reschedules the live job instead
+of restarting.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+
+from apscheduler.schedulers.background import BackgroundScheduler
+
+logger = logging.getLogger(__name__)
+
+
+class ScheduledJob:
+    """A named APScheduler job that awaits ``work()`` on the asyncio loop.
+
+    ``work`` is an async callable; exceptions it raises are logged under
+    ``label`` and never propagate into APScheduler's thread.
+    """
+
+    def __init__(self, job_id: str, work: Callable[[], Awaitable[None]], *, label: str) -> None:
+        self.job_id = job_id
+        self._work = work
+        self.label = label
+        self._scheduler: BackgroundScheduler | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    @property
+    def running(self) -> bool:
+        return self._scheduler is not None
+
+    def _fire(self) -> None:
+        """APScheduler invokes this from its worker thread; bridge into the loop."""
+        if self._loop is None:
+            logger.warning("%s scheduler: no loop registered", self.label)
+            return
+
+        async def _runner() -> None:
+            try:
+                await self._work()
+            except Exception:
+                logger.exception("%s run failed", self.label)
+
+        asyncio.run_coroutine_threadsafe(_runner(), self._loop)
+
+    def start(self, loop: asyncio.AbstractEventLoop, trigger, *, describe: str = "") -> None:
+        """Start the job on ``trigger``. Idempotent — a second start is a no-op."""
+        if self._scheduler is not None:
+            return
+        self._loop = loop
+        self._scheduler = BackgroundScheduler()
+        self._scheduler.add_job(
+            self._fire, trigger=trigger, id=self.job_id, replace_existing=True,
+        )
+        self._scheduler.start()
+        logger.info("%s scheduler started%s", self.label, f" ({describe})" if describe else "")
+
+    def reschedule(self, trigger, *, describe: str = "") -> None:
+        """Move the live job to a new trigger; a no-op when not running."""
+        if self._scheduler is None:
+            return
+        self._scheduler.reschedule_job(self.job_id, trigger=trigger)
+        logger.info("%s scheduler rescheduled%s", self.label, f" to {describe}" if describe else "")
+
+    def stop(self) -> None:
+        if self._scheduler is not None:
+            self._scheduler.shutdown(wait=False)
+            self._scheduler = None
+            logger.info("%s scheduler stopped", self.label)
@@ -8,6 +8,13 @@ from scribe.models.user import User

 logger = logging.getLogger(__name__)

+# What a stored credential looks like on the wire. Every surface that READS a
+# secret (smtp_password, forge_webhook_secret, a forge token) returns this
+# when one is set; every surface that WRITES one treats this value coming back
+# as "unchanged", never as a request to store eight asterisks over the real
+# credential. One constant so the read and write halves cannot disagree.
+SECRET_MASK = "********"
+

 async def get_admin_setting(key: str, default: str = "") -> str:
    """Read an instance-global setting (one stored on an admin account).
@@ -30,7 +30,8 @@ from typing import Iterable, NamedTuple
 from sqlalchemy import select

 from scribe.models import async_session
-from scribe.models.code_shape import CodeShape, CodeShapeEvent
+from scribe.models.code_shape import REASON_CODES, CodeShape, CodeShapeEvent, CodeShapeUse
+from scribe.models.base import iso

 logger = logging.getLogger(__name__)

@@ -64,6 +65,17 @@ def location_covers(loc_path: str, loc_symbol: str, path: str, name: str) -> boo
    return _path_touches(loc_path, path)


+# The rows the machine may still speak about: nobody's judgment stands on
+# them. `scoped` (#2869) is the sync's own by-construction stamp — the
+# proposer, derive grouping, divergence, hook evidence and sweeps treat it
+# like the todo; only the human todo (`unclassified`) excludes it.
+_MECHANICAL_TODO = ("unclassified", "scoped")
+_SCOPED_REASON = (
+    "by construction: a Vue component's scoped <style> rule / <script setup> "
+    "function — unreachable from any other file (stamped by the coverage sync)"
+)
+
+
 async def sync_repo_shapes(
    project_id: int,
    repo_key: str,
@@ -75,7 +87,9 @@ async def sync_repo_shapes(

    ``shapes`` are (path, kind, name) triples, or the richer ArchiveShape
    records (#2792) whose 4th/5th fields — signature, body_sha — refresh the
-    row's content fingerprint. ``seen_marker`` is the commit the archive was
+    row's content fingerprint, and whose 7th (#2869) says the shape is a
+    one-off by construction: such rows are stamped `scoped` (mechanical)
+    while unjudged, and un-stamped if a later tree makes them reachable. ``seen_marker`` is the commit the archive was
    read at when the forge can say, else the ref name — provenance sugar;
    the row timestamps carry the when.
    """
@@ -95,20 +109,32 @@ async def sync_repo_shapes(
            path, kind, name = shape[0], shape[1], shape[2]
            signature = shape[3] if len(shape) > 3 else ""
            body_sha = shape[4] if len(shape) > 4 else ""
+            scoped = bool(shape[6]) if len(shape) > 6 else False
            key = (path, name, kind)
            if key in seen:
                continue
            seen.add(key)
            row = by_key.get(key)
            if row is None:
-                session.add(CodeShape(
+                row = CodeShape(
                    project_id=project_id, repo_key=repo_key,
                    path=path, symbol=name, kind=kind,
                    first_seen_commit=seen_marker, last_seen_commit=seen_marker,
                    signature=signature, body_sha=body_sha,
-                ))
+                )
+                if scoped:
+                    await _judge(session, row, status="scoped", snippet_id=None,
+                                 by="mechanical", reason=_SCOPED_REASON, at=now)
+                else:
+                    session.add(row)
                continue
            row.last_seen_commit = seen_marker
+            if scoped and row.status == "unclassified":
+                await _judge(session, row, status="scoped", snippet_id=None,
+                             by="mechanical", reason=_SCOPED_REASON, at=now)
+            elif not scoped and row.status == "scoped":
+                await _judge(session, row, status="unclassified", snippet_id=None,
+                             by=None, reason=None, at=now)
            if signature:
                row.signature = signature
            if body_sha and body_sha != row.body_sha:
@@ -157,7 +183,7 @@ def _event(row: CodeShape, event: str, at: datetime, *, commit: str = "") -> Cod

 async def _judge(
    session, row: CodeShape, *, status: str, snippet_id: int | None,
-    by: str | None, reason: str | None, at: datetime,
+    by: str | None, reason: str | None, at: datetime, reason_code: str | None = None,
 ) -> None:
    """Apply a judgment to a row — the ONE place a status is set — and write
    its history. Clears what a judgment settles: the standing proposal, the
@@ -168,6 +194,7 @@ async def _judge(
    row.status = status
    row.snippet_id = snippet_id if status in _NEEDS_TARGET else None
    row.reason = (reason or "").strip() or None
+    row.reason_code = (reason_code or "").strip() or None
    row.classified_by = by if status != "unclassified" else None
    row.classified_at = at if status != "unclassified" else None
    row.classified_sha = row.body_sha if status != "unclassified" else ""
@@ -182,6 +209,59 @@ async def _judge(
    session.add(_event(row, "classified", at))


+async def record_uses(
+    session, row: CodeShape, snippet_ids, *, basis: str, evidence: str | None = None,
+) -> int:
+    """Upsert consumption edges shape → snippet (#2870). A judgment-grade
+    basis (agent/audit/import) overwrites a mechanical one (reference/hook)
+    on the same edge; mechanical never overwrites a judgment. Returns the
+    number of edges written or refreshed. The row must be persisted (flushed)
+    so it has an id."""
+    wanted = {int(x) for x in (snippet_ids or []) if x}
+    if not wanted:
+        return 0
+    if row.id is None:
+        session.add(row)
+        await session.flush()
+    existing = {
+        e.snippet_id: e
+        for e in (
+            await session.execute(
+                select(CodeShapeUse).where(CodeShapeUse.shape_id == row.id)
+            )
+        ).scalars().all()
+    }
+    judged = basis in _CALLER_VIAS
+    n = 0
+    for sid in wanted:
+        edge = existing.get(sid)
+        if edge is None:
+            session.add(CodeShapeUse(shape_id=row.id, snippet_id=sid, basis=basis, evidence=evidence))
+            n += 1
+        elif judged or edge.basis not in _CALLER_VIAS:
+            edge.basis, edge.evidence = basis, evidence
+            n += 1
+    return n
+
+
+async def uses_of(shape_ids) -> dict[int, list[CodeShapeUse]]:
+    """{shape_id: [edges]} for a set of rows — the read side of record_uses."""
+    ids = [int(x) for x in shape_ids if x]
+    if not ids:
+        return {}
+    async with async_session() as session:
+        edges = (
+            await session.execute(
+                select(CodeShapeUse).where(CodeShapeUse.shape_id.in_(ids))
+                .order_by(CodeShapeUse.shape_id, CodeShapeUse.snippet_id)
+            )
+        ).scalars().all()
+    out: dict[int, list[CodeShapeUse]] = {}
+    for e in edges:
+        out.setdefault(e.shape_id, []).append(e)
+    return out
+
+
 async def mark_canonicals(
    project_id: int, recorded: list[tuple[int, str, str]]
 ) -> None:
@@ -213,7 +293,7 @@ async def mark_canonicals(
                ),
                None,
            )
-            if covering is not None and row.status == "unclassified":
+            if covering is not None and row.status in _MECHANICAL_TODO:
                await _judge(session, row, status="canonical", snippet_id=covering,
                             by="mechanical", reason=None, at=now)
            elif (
@@ -288,6 +368,17 @@ def validate_classifications(items: list[dict]) -> str | None:
                f"classifications[{i}]: status {status!r} needs a reason — "
                "the WHY is the record (note 2786)"
            )
+        code = (item.get("reason_code") or "").strip()
+        if code and code not in REASON_CODES:
+            return (
+                f"classifications[{i}]: unknown reason_code {code!r} "
+                f"(one of: {', '.join(REASON_CODES)})"
+            )
+        uses = item.get("uses")
+        if uses is not None and (
+            not isinstance(uses, list) or not all(isinstance(u, int) and u > 0 for u in uses)
+        ):
+            return f"classifications[{i}]: uses must be a list of snippet ids"
    return None


@@ -326,6 +417,8 @@ async def classify_shapes(
        for item in classifications
        if item.get("status") in _NEEDS_TARGET
    }
+    for item in classifications:
+        target_ids.update(int(u) for u in (item.get("uses") or []))
    for sid in sorted(target_ids):
        if await snippets_svc.get_snippet(user_id, sid) is None:
            raise ValueError(f"snippet {sid} not found (or not readable)")
@@ -363,12 +456,101 @@ async def classify_shapes(
                    session, row, status=status,
                    snippet_id=int(item["snippet_id"]) if status in _NEEDS_TARGET else None,
                    by=via, reason=item.get("reason"), at=now,
+                    reason_code=item.get("reason_code"),
                )
+                if item.get("uses"):
+                    await record_uses(session, row, item["uses"], basis=via,
+                                      evidence=item.get("reason"))
                classified += 1
        await session.commit()
    return {"classified": classified, "unmatched": unmatched}


+def rule_matches(row: CodeShape, *, path: str, pattern: str, kind: str) -> bool:
+    """Does a ledger row fall under a rule-form classification (#2868)?
+    ``path`` is a file or a directory (everything beneath it), ``pattern``
+    a shell glob on the symbol (``""`` = every symbol), ``kind`` narrows to
+    sym/css. Pure, so the sweep's reach can be tested without a database."""
+    import fnmatch
+
+    clean = (path or "").strip().strip("/")
+    if clean and not (row.path == clean or row.path.startswith(clean + "/")):
+        return False
+    if kind and row.kind != kind:
+        return False
+    if pattern and not fnmatch.fnmatchcase(_norm_symbol(row.symbol), pattern):
+        return False
+    return True
+
+
+async def classify_shapes_where(
+    user_id: int,
+    project_id: int,
+    *,
+    path: str,
+    status: str,
+    pattern: str = "",
+    kind: str = "",
+    snippet_id: int | None = None,
+    reason: str | None = None,
+    via: str = "agent",
+    include_judged: bool = False,
+    reason_code: str | None = None,
+    uses: list[int] | None = None,
+) -> dict:
+    """The sweep form of classify_shapes (#2868): one judgment applied to
+    every live row under ``path`` whose symbol matches ``pattern`` (and
+    ``kind``). By default only unjudged rows are touched — `unclassified`
+    and the sync's mechanical `scoped` stamp — a sweep must never silently
+    overwrite a judgment; ``include_judged`` opts in.
+    Same gates as the row form (status vocabulary, snippet target, reason
+    for variant/exempt, write access); one transaction, so it applies whole
+    or not at all. Returns the count and a sample of what it judged."""
+    from scribe.services import access
+    from scribe.services import snippets as snippets_svc
+
+    if via not in _CALLER_VIAS:
+        raise ValueError(f"via must be one of: {', '.join(_CALLER_VIAS)}")
+    if not (path or "").strip():
+        raise ValueError("path is required — a sweep names the directory it judges")
+    if status == "canonical":
+        raise ValueError("canonical is the sync's stamp on a snippet's own location — a sweep cannot set it")
+    probe = {"path": path, "symbol": "*", "status": status,
+             "snippet_id": snippet_id or 0, "reason": reason or "",
+             "reason_code": reason_code or "", "uses": uses}
+    error = validate_classifications([probe])
+    if error:
+        raise ValueError(error.replace("classifications[0]", "rule"))
+    if not await access.can_write_project(user_id, project_id):
+        raise ValueError(f"project {project_id} not found or no write access")
+    if status in _NEEDS_TARGET and await snippets_svc.get_snippet(user_id, int(snippet_id)) is None:
+        raise ValueError(f"snippet {snippet_id} not found (or not readable)")
+    for sid in sorted({int(u) for u in (uses or [])}):
+        if await snippets_svc.get_snippet(user_id, sid) is None:
+            raise ValueError(f"snippet {sid} not found (or not readable)")
+
+    now = datetime.now(timezone.utc)
+    judged: list[str] = []
+    async with async_session() as session:
+        conds = [CodeShape.project_id == project_id, CodeShape.vanished_at.is_(None)]
+        if not include_judged:
+            conds.append(CodeShape.status.in_(_MECHANICAL_TODO))
+        rows = (await session.execute(select(CodeShape).where(*conds))).scalars().all()
+        for row in rows:
+            if not rule_matches(row, path=path, pattern=pattern, kind=kind):
+                continue
+            await _judge(
+                session, row, status=status,
+                snippet_id=int(snippet_id) if status in _NEEDS_TARGET else None,
+                by=via, reason=reason, at=now, reason_code=reason_code,
+            )
+            if uses:
+                await record_uses(session, row, uses, basis=via, evidence=reason)
+            judged.append(f"{row.path}::{row.symbol}")
+        await session.commit()
+    return {"classified": len(judged), "sample": sorted(judged)[:12]}
+
+
 async def list_project_shapes(
    user_id: int,
    project_id: int,
@@ -381,6 +563,7 @@ async def list_project_shapes(
    offset: int = 0,
    proposal: str = "",
    flag: str = "",
+    uses: int = 0,
 ) -> tuple[list[CodeShape], int]:
    """A filtered page of a project's ledger, with the unfiltered-match total.

@@ -426,6 +609,12 @@ async def list_project_shapes(
        conds.append(CodeShape.diverges_from.isnot(None))
    elif flag == "recheck":
        conds.append(CodeShape.recheck_at.isnot(None))
+    if uses:
+        # Consumers of a canon (#2870): rows with a uses edge to it, whatever
+        # shape they themselves are.
+        conds.append(CodeShape.id.in_(
+            select(CodeShapeUse.shape_id).where(CodeShapeUse.snippet_id == uses)
+        ))
    async with async_session() as session:
        total = (
            await session.execute(
@@ -476,18 +665,38 @@ async def snippet_consumers(user_id: int, note_id: int) -> dict:
                )
            )
        ).scalars().all()
-    readable: dict[int, bool] = {}
-    out: dict[str, list[dict]] = {"instances": [], "variants": []}
-    for row in rows:
-        if row.project_id not in readable:
-            readable[row.project_id] = await access.can_read_project(
-                user_id, row.project_id
+        # The consumption edges (#2870): rows that USE this canon, whatever
+        # shape they are themselves — the call-site map.
+        using = (
+            await session.execute(
+                select(CodeShape, CodeShapeUse.basis, CodeShapeUse.evidence)
+                .join(CodeShapeUse, CodeShapeUse.shape_id == CodeShape.id)
+                .where(CodeShapeUse.snippet_id == note_id, CodeShape.vanished_at.is_(None))
            )
-        if not readable[row.project_id]:
+        ).all()
+    readable: dict[int, bool] = {}
+
+    async def can_read(pid: int) -> bool:
+        if pid not in readable:
+            readable[pid] = await access.can_read_project(user_id, pid)
+        return readable[pid]
+
+    out: dict[str, list[dict]] = {"instances": [], "variants": [], "uses": []}
+    for row in rows:
+        if not await can_read(row.project_id):
            continue
        out["instances" if row.status == "instance" else "variants"].append(
            _consumer_dict(row)
        )
+    for row, basis, evidence in using:
+        if not await can_read(row.project_id):
+            continue
+        d = _consumer_dict(row)
+        d["basis"] = basis
+        if evidence:
+            d["evidence"] = evidence
+        d.pop("reason", None)
+        out["uses"].append(d)
    return out


@@ -659,7 +868,7 @@ async def stamp_write_path_instances(
                )
                session.add(row)
                by_key[(name, kind)] = row
-            elif not (row.status == "unclassified" or row.classified_by == "hook"):
+            elif not (row.status in _MECHANICAL_TODO or row.classified_by == "hook"):
                continue  # a judgment — or the canon itself — stands
            await _judge(session, row, status="instance", snippet_id=sid, by="hook",
                         reason=why, at=now)
@@ -667,6 +876,13 @@ async def stamp_write_path_instances(
                "path": path, "symbol": name, "kind": kind,
                "snippet_id": sid, "reason": why,
            })
+            # Every pulled canon the payload NAMES is a uses edge (#2870) — the
+            # call-site fact, independent of which one the row is judged to be.
+            await record_uses(
+                session, row,
+                [s_id for rank, _at, s_id, _why in bucket if rank == 2],
+                basis="hook", evidence="write path: pulled the snippet, payload names its symbol",
+            )
        if stamped:
            await session.commit()
    return stamped
@@ -717,7 +933,9 @@ _SEMANTIC_CAP = 150
 _SEMANTIC_FLOOR = 0.8
 # Bump when a basis's rule changes: rows remember the (body, ruleset) they
 # were examined under, so a tightened rule re-examines everything once.
-_PROPOSER_VERSION = 2
+# v3: language-family gate on the sym bases, reference stoplist, semantic
+# restricted to the shape's own project (#2871).
+_PROPOSER_VERSION = 3
 # Signature resemblance floor, name blanked (difflib ratio) — and a length
 # floor, because `def NAME():` resembles `def NAME(x):` at 0.95 while saying
 # nothing; a family shape has parameters to resemble.
@@ -736,6 +954,64 @@ class Canon(NamedTuple):
    signature: str
    code_norm: str
    project_id: int = 0
+    language: str = ""   # the snippet's recorded language; "" = unknown, no gate
+
+
+# Language families: the sym bases only propose within one. The 2026-08
+# audit (#2871) found every cross-language hit wrong — a Python tool-module
+# canon named `register` proposed for Vue `handleSubmit`s that call
+# `authStore.register()`, and a TS store's `register` matched it by symbol;
+# Minstrel/Forge TS canon proposed for Python bodies by resemblance. CSS is
+# its own kind and is not gated here.
+_FAMILY_BY_LANG = {
+    "python": "py", "py": "py",
+    "typescript": "js", "ts": "js", "tsx": "js", "javascript": "js", "js": "js",
+    "jsx": "js", "vue": "js", "mjs": "js", "cjs": "js",
+    "css": "css", "scss": "css", "sass": "css", "less": "css",
+    "bash": "sh", "sh": "sh", "shell": "sh", "zsh": "sh",
+    "sql": "sql",
+}
+_FAMILY_BY_EXT = {
+    ".py": "py", ".pyi": "py",
+    ".ts": "js", ".tsx": "js", ".js": "js", ".jsx": "js", ".vue": "js", ".mjs": "js", ".cjs": "js",
+    ".css": "css", ".scss": "css", ".sass": "css", ".less": "css",
+    ".sh": "sh", ".bash": "sh", ".zsh": "sh",
+    ".sql": "sql",
+}
+
+
+def language_family(language: str) -> str:
+    """The family a recorded snippet language belongs to ("" when unknown)."""
+    return _FAMILY_BY_LANG.get((language or "").strip().lower(), "")
+
+
+def path_family(path: str) -> str:
+    """The family a file path belongs to, by extension ("" when unknown)."""
+    p = (path or "").lower()
+    for ext, fam in _FAMILY_BY_EXT.items():
+        if p.endswith(ext):
+            return fam
+    return ""
+
+
+def same_family(path: str, canon_language: str) -> bool:
+    """A sym basis may propose this canon for this path: both families known
+    and equal, or either unknown (no evidence either way → no gate)."""
+    a = path_family(path)
+    b = language_family(canon_language)
+    return not a or not b or a == b
+
+
+# Reference basis: generic verbs name too many unrelated things to count a
+# bare mention as a call site of THIS canon (`register`, `load`, `save` …).
+# The symbol basis still catches a second definition of such a name; the
+# call-site relation for these becomes a `uses` edge once #2870 lands.
+_REFERENCE_STOPLIST = frozenset({
+    "get", "set", "put", "post", "load", "save", "run", "main", "init", "setup",
+    "register", "restore", "reset", "toggle", "close", "open", "submit", "handler",
+    "update", "create", "delete", "remove", "add", "start", "stop", "send",
+    "receive", "render", "mount", "dispatch", "call", "apply", "execute",
+})


 def _norm_text(text: str) -> str:
@@ -767,6 +1043,26 @@ def text_contains(body: str, code: str) -> bool:
    return a in b or b in a


+def reference_canons(kind: str, path: str, symbol: str, body: str, canons: Iterable[Canon]) -> list[int]:
+    """Every canon this body NAMES (#2870) — the uses edges the proposer can
+    write mechanically: same kind, same language family, symbol not in the
+    generic-verb stoplist, and not the shape's own name."""
+    norm_sym = _norm_symbol(symbol)
+    out: list[int] = []
+    for c in canons:
+        if c.kind != kind or not c.symbol:
+            continue
+        if kind == "sym" and not same_family(path, c.language):
+            continue
+        if _norm_symbol(c.symbol) == norm_sym:
+            continue
+        if _norm_symbol(c.symbol).lower() in _REFERENCE_STOPLIST:
+            continue
+        if references_symbol(body, c.symbol, kind):
+            out.append(c.snippet_id)
+    return out
+
+
 def match_canon(
    kind: str, path: str, symbol: str, signature: str, body: str,
    canons: Iterable[Canon], *, project_id: int = 0,
@@ -788,11 +1084,17 @@ def match_canon(
    for c in canons:
        if c.kind != kind:
            continue
+        if kind == "sym" and not same_family(path, c.language):
+            continue  # a Python canon says nothing about a Vue body, and vice versa
        if c.symbol and _norm_symbol(c.symbol) == norm_sym:
            if not any(location_covers(lp, ls, path, symbol) for lp, ls in c.locations):
                offer("symbol", 1.0, c)
            continue  # its own location is canonical territory, not a proposal
-        if c.symbol and references_symbol(body, c.symbol, kind):
+        if (
+            c.symbol
+            and _norm_symbol(c.symbol).lower() not in _REFERENCE_STOPLIST
+            and references_symbol(body, c.symbol, kind)
+        ):
            offer("reference", 0.9, c)
        if c.code_norm and text_contains(body, c.code_norm):
            offer("text", 0.95, c)
@@ -848,6 +1150,7 @@ async def canon_catalog(user_id: int) -> list[Canon]:
                for loc in fields.get("locations") or []
            ),
            signature, _norm_text(code), int(note.project_id or 0),
+            (fields.get("language") or "").strip().lower(),
        ))
    return out

@@ -906,7 +1209,14 @@ async def propose_for_repo(
    if canons is None:
        canons = await canon_catalog(user_id)
    by_key = {(d[0], d[1], d[2]): d for d in definitions}
-    sym_canon_ids = {c.snippet_id for c in canons if c.kind == "sym"}
+    # The semantic arm is the widest net and, across projects, was pure noise
+    # in the 2026-08 audit (#2871): it is held to the shape's own project and
+    # language family. The precise bases (symbol/text) still reach family
+    # canon in other projects (note 2786).
+    sym_canons = [c for c in canons if c.kind == "sym" and c.project_id == project_id]
+
+    def semantic_allowed(path: str) -> set[int]:
+        return {c.snippet_id for c in sym_canons if same_family(path, c.language)}
    now = datetime.now(timezone.utc)
    examined = proposed = checked = 0
    async with async_session() as session:
@@ -915,7 +1225,7 @@ async def propose_for_repo(
                select(CodeShape).where(
                    CodeShape.project_id == project_id,
                    CodeShape.repo_key == repo_key,
-                    CodeShape.status == "unclassified",
+                    CodeShape.status.in_(_MECHANICAL_TODO),
                    CodeShape.vanished_at.is_(None),
                )
            )
@@ -939,6 +1249,12 @@ async def propose_for_repo(
            row.proposal_group = group
            row.proposed_at = now
            row.proposed_sha = examined_as
+            # Consumption is recorded for every canon the body names (#2870),
+            # whatever the row is then judged to be.
+            used = reference_canons(row.kind, row.path, row.symbol, body, canons)
+            if used:
+                await record_uses(session, row, used, basis="reference",
+                                  evidence="proposer: body names the canon's symbol")
            if hit:
                row.proposed_snippet_id, row.proposal_basis, row.proposal_score = hit
                row.proposal_group = None
@@ -954,7 +1270,7 @@ async def propose_for_repo(
                continue
            checked += 1
            try:
-                found = await _semantic_canon(user_id, d[5], sym_canon_ids)
+                found = await _semantic_canon(user_id, d[5], semantic_allowed(row.path))
            except Exception:
                logger.warning("semantic proposal failed", exc_info=True)
                found = None
@@ -1004,7 +1320,7 @@ async def apply_derive_groups(project_id: int) -> int:
            await session.execute(
                select(CodeShape).where(
                    CodeShape.project_id == project_id,
-                    CodeShape.status == "unclassified",
+                    CodeShape.status.in_(_MECHANICAL_TODO),
                    CodeShape.vanished_at.is_(None),
                    CodeShape.proposed_snippet_id.is_(None),
                )
@@ -1037,27 +1353,44 @@ def proposal_summary(rows: Iterable[CodeShape], *, top: int = 8) -> dict:
    """The readout's view of the proposer's standing: how many canon
    proposals await confirmation, and the largest derive-first groups."""
    proposed = 0
+    by_canon: dict[int, int] = {}
    groups: dict[str, dict] = {}
+    files: dict[str, set[str]] = {}
    for row in rows:
-        if row.status != "unclassified":
+        if row.status not in _MECHANICAL_TODO:
            continue
        if row.proposed_snippet_id is not None:
            proposed += 1
+            by_canon[row.proposed_snippet_id] = by_canon.get(row.proposed_snippet_id, 0) + 1
        elif row.proposal_group:
+            dup = not row.proposal_group.startswith("name:")
            g = groups.setdefault(row.proposal_group, {
                "group": row.proposal_group, "kind": row.kind,
                "label": (
-                    ("." if row.kind == "css" else "") + row.symbol
-                    if row.proposal_group.startswith("name:")
-                    else f"{row.symbol} (identical body)"
+                    f"{row.symbol} (identical body)" if dup
+                    else ("." if row.kind == "css" else "") + row.symbol
                ),
-                "size": 0, "paths": [],
+                "size": 0, "files": 0, "paths": [],
            })
            g["size"] += 1
+            files.setdefault(row.proposal_group, set()).add(row.path)
            if len(g["paths"]) < 3:
                g["paths"].append(row.path)
-    ranked = sorted(groups.values(), key=lambda g: (-g["size"], g["group"]))
-    return {"proposed": proposed, "derive_groups": ranked[:top]}
+    for key, g in groups.items():
+        g["files"] = len(files[key])
+    # Body-identical groups first (#2872): the things an audit actually
+    # consolidated were identical bodies under different names/files; a
+    # name repeated across modules is usually convention. Within a tier,
+    # the group spread over more files is the bigger copy.
+    ranked = sorted(
+        groups.values(),
+        key=lambda g: (g["group"].startswith("name:"), -g["files"], -g["size"], g["group"]),
+    )
+    top_canon = None
+    if by_canon:
+        sid, n = max(by_canon.items(), key=lambda kv: (kv[1], -kv[0]))
+        top_canon = {"snippet_id": sid, "count": n}
+    return {"proposed": proposed, "derive_groups": ranked[:top], "top_canon": top_canon}


 async def confirm_proposals(
@@ -1088,7 +1421,7 @@ async def confirm_proposals(

    conds = [
        CodeShape.project_id == project_id,
-        CodeShape.status == "unclassified",
+        CodeShape.status.in_(_MECHANICAL_TODO),
        CodeShape.vanished_at.is_(None),
        CodeShape.proposed_snippet_id.isnot(None),
    ]
@@ -1245,7 +1578,7 @@ async def flag_divergence(project_id: int, *, since: datetime | None) -> int:
        for siblings in by_dir.values():
            dom = dominant_canon(siblings)
            for r in siblings:
-                if r.status != "unclassified":
+                if r.status not in _MECHANICAL_TODO:
                    continue
                if r.diverges_from is not None:
                    flagged += 1
@@ -1262,7 +1595,7 @@ async def flag_divergence(project_id: int, *, since: datetime | None) -> int:

 def divergence_summary(rows: Iterable[CodeShape], *, top: int = 10) -> dict:
    """Readout view: flagged shapes (newest first) and the recheck count."""
-    flagged = [r for r in rows if r.diverges_from is not None and r.status == "unclassified"]
+    flagged = [r for r in rows if r.diverges_from is not None and r.status in _MECHANICAL_TODO]
    flagged.sort(key=lambda r: (r.created_at or datetime.min.replace(tzinfo=timezone.utc)), reverse=True)
    recheck = sum(1 for r in rows if r.recheck_at is not None and r.vanished_at is None)
    return {
@@ -1318,9 +1651,9 @@ async def shape_history(
                "classified_by": r.classified_by, "reason": r.reason,
                "first_seen_commit": r.first_seen_commit,
                "last_seen_commit": r.last_seen_commit,
-                "first_seen_at": r.created_at.isoformat() if r.created_at else None,
-                "vanished_at": r.vanished_at.isoformat() if r.vanished_at else None,
-                "recheck_at": r.recheck_at.isoformat() if r.recheck_at else None,
+                "first_seen_at": iso(r.created_at),
+                "vanished_at": iso(r.vanished_at),
+                "recheck_at": iso(r.recheck_at),
                "diverges_from": r.diverges_from,
            }
            for r in rows
@@ -10,6 +10,7 @@ from scribe.models.note import Note
 from scribe.models.project import Project
 from scribe.models.share import NoteShare, ProjectShare
 from scribe.models.user import User
+from scribe.models.base import iso

 logger = logging.getLogger(__name__)

@@ -31,7 +32,7 @@ async def _enrich_shares(session, shares) -> list[dict]:
    return result


-def _deduplicate_by_permission(shares, id_attr: str) -> dict[int, str]:
+def best_permission_by(shares, id_attr: str) -> dict[int, str]:
    """Return {resource_id: best_permission} keeping the highest-ranked permission per resource."""
    from scribe.services.access import PERMISSION_RANK
    seen: dict[int, str] = {}
@@ -210,7 +211,7 @@ async def list_shared_with_me(user_id: int) -> dict:
                )
            )).scalars().all()

-        seen_projects = _deduplicate_by_permission(list(proj_direct) + list(proj_group), "project_id")
+        seen_projects = best_permission_by(list(proj_direct) + list(proj_group), "project_id")

        projects = []
        for pid, perm in seen_projects.items():
@@ -223,7 +224,7 @@ async def list_shared_with_me(user_id: int) -> dict:
                    "description": proj.description,
                    "status": proj.status,
                    "color": proj.color,
-                    "updated_at": proj.updated_at.isoformat(),
+                    "updated_at": iso(proj.updated_at),
                    "owner_username": owner.username if owner else None,
                    "permission": perm,
                })
@@ -241,7 +242,7 @@ async def list_shared_with_me(user_id: int) -> dict:
                )
            )).scalars().all()

-        seen_notes = _deduplicate_by_permission(list(note_direct) + list(note_group), "note_id")
+        seen_notes = best_permission_by(list(note_direct) + list(note_group), "note_id")

        notes = []
        for nid, perm in seen_notes.items():
@@ -253,7 +254,7 @@ async def list_shared_with_me(user_id: int) -> dict:
                    "title": note.title,
                    "is_task": note.is_task,
                    "project_id": note.project_id,
-                    "updated_at": note.updated_at.isoformat(),
+                    "updated_at": iso(note.updated_at),
                    "owner_username": owner.username if owner else None,
                    "permission": perm,
                })
@@ -181,3 +181,35 @@ async def superseded_ids(note_ids: list[int]) -> set[int]:
            .where(NoteSupersession.superseded_id.in_(note_ids))
        )).scalars().all()
    return {int(r) for r in rows}
+
+
+SUPERSEDED_HINT = (
+    "A later note claims to bring this up to date — see superseded_by. "
+    "Read this as what was true when written, and check the newer one "
+    "before acting on it."
+)
+
+
+async def attach_relations(user_id: int, note_id: int, data: dict, *, hint: bool = False) -> None:
+    """Add both directions of the supersession relation to a note payload.
+
+    ONE seam for the REST and MCP surfaces, which must agree about what a
+    note's payload says — or the web UI and the agent would disagree about
+    whether a record is current. Both directions, because they answer
+    different questions and only one is obvious: `supersedes` is what the
+    author claimed; `superseded_by` is what a READER needs and what the note
+    itself cannot know — a stale record handed over without that marker gets
+    acted on confidently, which is worse than never surfacing it.
+
+    Omitted entirely when empty, so an ordinary note's payload doesn't grow
+    two permanently-empty lists (#2483 — a field that always says nothing
+    trains readers to skip fields). `hint=True` (the agent surface) also
+    attaches `superseded_note`, the one-sentence reading instruction.
+    """
+    rel = await get_relations(user_id, note_id)
+    if rel["supersedes"]:
+        data["supersedes"] = rel["supersedes"]
+    if rel["superseded_by"]:
+        data["superseded_by"] = rel["superseded_by"]
+        if hint:
+            data["superseded_note"] = SUPERSEDED_HINT
@@ -8,15 +8,16 @@ trashed rows via `alive()`.
 from __future__ import annotations

 import uuid
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone

-from sqlalchemy import or_, select, update
+from sqlalchemy import delete as sql_delete, or_, select, update

 from scribe.models import async_session
 from scribe.models.note import Note
 from scribe.models.project import Project
 from scribe.models.milestone import Milestone
 from scribe.models.rulebook import Rulebook, RulebookTopic, Rule
+from scribe.models.base import iso

 # entity_type -> Model. Used to resolve which table a trash op targets.
 _MODEL_FOR = {
@@ -87,16 +88,15 @@ async def _cascade(session, user_id: int, etype: str, eid: int, batch: str, now)
        # FK CASCADE would handle a full DELETE on the project row, but the
        # soft-delete path keeps the project row alive; this guarantees the
        # rows are gone whether or not the project ever gets purged.
-        from sqlalchemy import delete as _sql_delete
        from scribe.models.rulebook import (
            project_rule_suppressions, project_topic_suppressions,
        )
        await session.execute(
-            _sql_delete(project_rule_suppressions)
+            sql_delete(project_rule_suppressions)
            .where(project_rule_suppressions.c.project_id == eid)
        )
        await session.execute(
-            _sql_delete(project_topic_suppressions)
+            sql_delete(project_topic_suppressions)
            .where(project_topic_suppressions.c.project_id == eid)
        )
        await _set(session, Project, [Project.user_id == user_id, Project.id == eid], batch, now)
@@ -213,7 +213,6 @@ async def restore_entity(user_id: int, entity_type: str, entity_id: int) -> int

 async def purge(user_id: int, batch_id: str) -> int:
    """Hard-delete every row in the batch. Irreversible."""
-    from sqlalchemy import delete as sql_delete
    n = 0
    async with async_session() as session:
        for model in _ALL:
@@ -241,7 +240,7 @@ async def list_trash(user_id: int) -> list[dict]:
                grp = batches.setdefault(
                    r.deleted_batch_id,
                    {"batch_id": r.deleted_batch_id,
-                     "deleted_at": r.deleted_at.isoformat() if r.deleted_at else None,
+                     "deleted_at": iso(r.deleted_at),
                     "items": []},
                )
                grp["items"].append({
@@ -265,8 +264,6 @@ async def purge_expired(user_id: int, retention_days: int) -> int:
    user's short window prematurely destroy another's data.
    retention_days <= 0 disables auto-purge (returns 0 without touching anything).
    """
-    from datetime import timedelta
-    from sqlalchemy import delete as sql_delete
    if retention_days <= 0:
        return 0
    cutoff = datetime.now(timezone.utc) - timedelta(days=retention_days)
@@ -1,80 +1,50 @@
 """Daily APScheduler cron that purges expired trash.

-Mirrors version_pinning_scheduler.py: a single global BackgroundScheduler job
-at 03:30 UTC bridges into the asyncio loop to run the async purge. Iterates
-every user and applies that user's own `trash_retention_days` setting; 0
-disables auto-purge for that user.
+A single job at 03:30 UTC (services/scheduler.py). Iterates every user and
+applies that user's own `trash_retention_days` setting; 0 disables auto-purge
+for that user.
 """
 from __future__ import annotations

 import asyncio
 import logging

-from apscheduler.schedulers.background import BackgroundScheduler
 from apscheduler.triggers.cron import CronTrigger
+from sqlalchemy import select

+from scribe.models import async_session
+from scribe.models.user import User
 from scribe.services import trash as trash_svc
+from scribe.services.scheduler import ScheduledJob
 from scribe.services.settings import get_setting

 logger = logging.getLogger(__name__)

-_scheduler: BackgroundScheduler | None = None
-_loop: asyncio.AbstractEventLoop | None = None

+async def _run_purge() -> None:
+    async with async_session() as session:
+        user_ids = (await session.execute(select(User.id))).scalars().all()

-def _run_purge_threadsafe() -> None:
-    """APScheduler invokes this from a worker thread; bridge into the loop."""
-    if _loop is None:
-        logger.warning("trash scheduler: no loop registered")
-        return
-
-    async def _runner():
+    purged = 0
+    for uid in user_ids:
+        raw = await get_setting(uid, "trash_retention_days", "90")
        try:
-            from sqlalchemy import select
+            days = int(raw)
+        except (TypeError, ValueError):
+            days = 90
+        purged += await trash_svc.purge_expired(uid, days)
+    if purged:
+        logger.info("trash purge: removed %d expired row(s)", purged)
+    else:
+        logger.debug("trash purge: nothing expired")

-            from scribe.models import async_session
-            from scribe.models.user import User

-            async with async_session() as session:
-                user_ids = (await session.execute(select(User.id))).scalars().all()
-
-            purged = 0
-            for uid in user_ids:
-                raw = await get_setting(uid, "trash_retention_days", "90")
-                try:
-                    days = int(raw)
-                except (TypeError, ValueError):
-                    days = 90
-                purged += await trash_svc.purge_expired(uid, days)
-            if purged:
-                logger.info("trash purge: removed %d expired row(s)", purged)
-            else:
-                logger.debug("trash purge: nothing expired")
-        except Exception:
-            logger.exception("trash purge run failed")
-
-    asyncio.run_coroutine_threadsafe(_runner(), _loop)
+_JOB = ScheduledJob("trash_retention_purge", _run_purge, label="Trash retention")


 def start_trash_scheduler(loop: asyncio.AbstractEventLoop) -> None:
-    global _scheduler, _loop
-    if _scheduler is not None:
-        return
-    _loop = loop
-    _scheduler = BackgroundScheduler()
-    _scheduler.add_job(
-        _run_purge_threadsafe,
-        trigger=CronTrigger(hour=3, minute=30, timezone="UTC"),
-        id="trash_retention_purge",
-        replace_existing=True,
-    )
-    _scheduler.start()
-    logger.info("Trash retention scheduler started (daily 03:30 UTC)")
+    _JOB.start(loop, CronTrigger(hour=3, minute=30, timezone="UTC"), describe="daily 03:30 UTC")


 def stop_trash_scheduler() -> None:
-    global _scheduler
-    if _scheduler is not None:
-        _scheduler.shutdown(wait=False)
-        _scheduler = None
-        logger.info("Trash retention scheduler stopped")
+    _JOB.stop()
@@ -5,68 +5,39 @@ system promotes stable note versions before they get aged out of the
 rolling cap. Off-hours by design — the scan is cheap but not time-
 critical and doesn't need to interrupt regular activity.

-Mirrors the BackgroundScheduler + threadsafe-async-call pattern used by
-journal_scheduler.py.
+One ScheduledJob (services/scheduler.py), like the other *_scheduler modules.
 """
 from __future__ import annotations

 import asyncio
 import logging

-from apscheduler.schedulers.background import BackgroundScheduler
 from apscheduler.triggers.cron import CronTrigger

+from scribe.services.scheduler import ScheduledJob
 from scribe.services.version_pinning import scan_all_users_for_auto_pins

 logger = logging.getLogger(__name__)

-_scheduler: BackgroundScheduler | None = None
-_loop: asyncio.AbstractEventLoop | None = None
+
+async def _run_scan() -> None:
+    results = await scan_all_users_for_auto_pins()
+    total = sum(results.values())
+    if total > 0:
+        logger.info(
+            "auto-pin scan: pinned %d version(s) across %d user(s)",
+            total, len(results),
+        )
+    else:
+        logger.debug("auto-pin scan: no new pins")


-def _run_scan_threadsafe() -> None:
-    """APScheduler invokes this from a worker thread; bridge into the
-    asyncio loop so the scan can await its DB operations."""
-    if _loop is None:
-        logger.warning("version_pinning scheduler: no loop registered")
-        return
-
-    async def _runner():
-        try:
-            results = await scan_all_users_for_auto_pins()
-            total = sum(results.values())
-            if total > 0:
-                logger.info(
-                    "auto-pin scan: pinned %d version(s) across %d user(s)",
-                    total, len(results),
-                )
-            else:
-                logger.debug("auto-pin scan: no new pins")
-        except Exception:
-            logger.exception("auto-pin scan run failed")
-
-    asyncio.run_coroutine_threadsafe(_runner(), _loop)
+_JOB = ScheduledJob("version_pinning_auto_scan", _run_scan, label="Version pinning")


 def start_version_pinning_scheduler(loop: asyncio.AbstractEventLoop) -> None:
-    global _scheduler, _loop
-    if _scheduler is not None:
-        return
-    _loop = loop
-    _scheduler = BackgroundScheduler()
-    _scheduler.add_job(
-        _run_scan_threadsafe,
-        trigger=CronTrigger(hour=3, minute=0, timezone="UTC"),
-        id="version_pinning_auto_scan",
-        replace_existing=True,
-    )
-    _scheduler.start()
-    logger.info("Version pinning scheduler started (daily 03:00 UTC)")
+    _JOB.start(loop, CronTrigger(hour=3, minute=0, timezone="UTC"), describe="daily 03:00 UTC")


 def stop_version_pinning_scheduler() -> None:
-    global _scheduler
-    if _scheduler is not None:
-        _scheduler.shutdown(wait=False)
-        _scheduler = None
-        logger.info("Version pinning scheduler stopped")
+    _JOB.stop()
@@ -6,9 +6,19 @@ instance (e.g. a Docker service spun up by the CI job) and set DATABASE_URL
 in the environment before importing the app.

 For unit tests of pure functions no database is needed at all.
+
+The fixtures below are the ONE definition of three things that used to be
+copied into a dozen test modules each (#2825). They are deliberately not
+autouse: a module opts in with
+``pytestmark = pytest.mark.usefixtures("<name>")`` (or a test names the
+fixture as a parameter), so a unit test that never touches the engine or the
+MCP context pays nothing for them.
 """
 import os
+from unittest.mock import AsyncMock, patch
+
 import pytest
+import pytest_asyncio


@pytest.fixture(autouse=True)
@@ -23,3 +33,52 @@ def _isolate_env(request, monkeypatch):
    monkeypatch.setenv("DATABASE_URL", "postgresql+asyncpg://test:test@localhost/test")
    monkeypatch.setenv("SECRET_KEY", "test-secret-key")
    monkeypatch.setenv("OLLAMA_URL", "http://localhost:11434")
+
+
+@pytest.fixture
+def _bind_user():
+    """Bind MCP caller #7 for the duration of a test.
+
+    The MCP tool layer reads the caller from a ContextVar the HTTP transport
+    sets per request; a unit test of a tool has no request, so it binds the
+    caller itself. Every tool-layer test module opts in with
+    ``pytestmark = pytest.mark.usefixtures("_bind_user")`` and builds its fakes
+    with user_id=7 so ownership checks see the caller as the owner.
+    """
+    from scribe.mcp._context import _user_id_ctx
+
+    token = _user_id_ctx.set(7)
+    yield
+    _user_id_ctx.reset(token)
+
+
+@pytest_asyncio.fixture
+async def _dispose_engine():
+    """Dispose the app's module-level engine after a test that hit Postgres.
+
+    The engine pools asyncpg connections per event loop, but pytest-asyncio
+    runs each test on a fresh loop — so without this, test 2 gets handed
+    test 1's connection bound to a now-dead loop ("Future attached to a
+    different loop"). Disposing in the test's own loop teardown clears the
+    pool cleanly. The import is deferred so merely collecting a module that
+    mixes unit and integration tests never builds an engine.
+    """
+    from scribe.models import engine
+
+    yield
+    await engine.dispose()
+
+
+@pytest.fixture
+def _no_supersession():
+    """Stub the auto-inject menu's "which lines are superseded?" lookup (#278).
+
+    That is a real database call on a path the plugin-context tests exercise
+    without one. Stubbed to "nothing superseded" — the ordinary state — rather
+    than hidden behind a try/except in the product, which would make the code
+    lie about what it does. The label's own behaviour is covered in
+    tests/test_supersession_ranking.py.
+    """
+    with patch("scribe.services.plugin_context.superseded_ids",
+               AsyncMock(return_value=set())):
+        yield
@@ -0,0 +1,184 @@
+"""Shared test helpers — the plain functions tests call, as opposed to the
+fixtures in conftest.py.
+
+Each of these was copied into several test modules before #2825 consolidated
+them; a module imports what it needs with ``from tests.helpers import ...``.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+
+def make_mock_session() -> AsyncMock:
+    """A stand-in for ``async_session()`` — usable as ``async with``, with the
+    commit/refresh/add surface a service touches.
+
+    ``add`` is a MagicMock because the real ``Session.add`` is synchronous;
+    an AsyncMock there would hand the service an un-awaited coroutine.
+    """
+    s = AsyncMock()
+    s.__aenter__ = AsyncMock(return_value=s)
+    s.__aexit__ = AsyncMock(return_value=False)
+    s.add = MagicMock()
+    s.commit = AsyncMock()
+    s.refresh = AsyncMock()
+    return s
+
+
+async def ensure_user(session, username: str, role: str = "user"):
+    """Get-or-create a User by username inside an open session (flushed, not
+    committed).
+
+    Integration tests share one database for the whole lane run, so a second
+    test re-creating the same username dies on the unique constraint —
+    every integration seed goes through this instead of ``User(...)`` + add.
+    """
+    from sqlalchemy import select
+
+    from scribe.models.user import User
+
+    existing = (
+        await session.execute(select(User).where(User.username == username))
+    ).scalar_one_or_none()
+    if existing is not None:
+        return existing
+    user = User(username=username, role=role)
+    session.add(user)
+    await session.flush()
+    return user
+
+
+def fake_record(**attrs) -> MagicMock:
+    """A MagicMock record with REAL values on the attributes named, and a
+    ``to_dict()`` that mirrors them.
+
+    The hazard this exists for (note 2109): an auto-created MagicMock attribute
+    is truthy and has a repr — so a bare MagicMock handed to the product reads
+    as trashed, shared, a task, and owned by a MagicMock. Name every attribute
+    the code under test will read; the per-model ``fake_*`` builders below
+    carry the ordinary defaults so a call site states only what the test is
+    about. ``created_at`` / ``updated_at`` are set as attributes but kept out
+    of ``to_dict()`` (no test serialises them, and the real models isoformat
+    them).
+    """
+    n = MagicMock()
+    for key, value in attrs.items():
+        setattr(n, key, value)
+    n.to_dict.return_value = {
+        k: v for k, v in attrs.items() if k not in ("created_at", "updated_at")
+    }
+    return n
+
+
+def _with_defaults(defaults: dict, attrs: dict) -> MagicMock:
+    values = dict(defaults)
+    values.update(attrs)
+    return fake_record(**values)
+
+
+def _now():
+    return datetime.now(timezone.utc)
+
+
+def fake_note(**attrs) -> MagicMock:
+    """A stand-in Note: own (user_id=7, the caller `_bind_user` binds), live,
+    not a task, no structured data. The injected menu reads is_task /
+    task_kind / note_type for its kind marker, user_id for the "shared by …"
+    attribution, data for a snippet's language, deleted_at for trash."""
+    return _with_defaults({
+        "id": 1, "title": "t", "body": "", "tags": [], "user_id": 7,
+        "note_type": "note", "is_task": False, "task_kind": "work",
+        "data": None, "deleted_at": None,
+    }, attrs)
+
+
+def fake_task(**attrs) -> MagicMock:
+    """A stand-in task note — get_task reads parent_id, deleted_at, user_id."""
+    return _with_defaults({
+        "id": 1, "title": "t", "body": "", "status": "todo", "priority": "none",
+        "tags": [], "parent_id": None, "project_id": None, "is_task": True,
+        "task_kind": "work", "user_id": 7, "deleted_at": None,
+    }, attrs)
+
+
+def fake_snippet(**attrs) -> MagicMock:
+    """A stand-in snippet note. ``data`` is explicitly None: snippet_fields
+    prefers `data` when truthy, and a MagicMock is truthy."""
+    return _with_defaults({
+        "id": 1, "title": "debounce — rate-limit a callback",
+        "body": "```js\nreturn 1\n```\n", "tags": ["js", "snippet"],
+        "note_type": "snippet", "is_task": False, "task_kind": "work",
+        "user_id": 7, "data": None, "deleted_at": None,
+    }, attrs)
+
+
+def fake_project(**attrs) -> MagicMock:
+    """design_system_id is explicit: a truthy auto-attribute would route every
+    project through the design-system branch and out to a real database."""
+    return _with_defaults({
+        "id": 1, "title": "P", "description": "", "goal": "", "status": "active",
+        "color": None, "design_system_id": None, "user_id": 7,
+    }, attrs)
+
+
+def fake_milestone(**attrs) -> MagicMock:
+    return _with_defaults({
+        "id": 1, "project_id": 1, "title": "MS", "description": None,
+        "status": "active", "order_index": 0,
+    }, attrs)
+
+
+def fake_system(**attrs) -> MagicMock:
+    return _with_defaults({"id": 1, "name": "Reader", "project_id": 5}, attrs)
+
+
+def fake_rulebook(**attrs) -> MagicMock:
+    return _with_defaults({
+        "id": 1, "owner_user_id": 7, "title": "FabledSword family",
+        "description": "", "created_at": _now(), "updated_at": _now(),
+    }, attrs)
+
+
+def fake_topic(**attrs) -> MagicMock:
+    return _with_defaults({
+        "id": 10, "rulebook_id": 1, "title": "git-workflow", "description": "",
+        "order_index": 0, "created_at": _now(), "updated_at": _now(),
+    }, attrs)
+
+
+def fake_rule(**attrs) -> MagicMock:
+    return _with_defaults({
+        "id": 1, "topic_id": 10, "title": "dev is home",
+        "statement": "Work directly on dev", "why": "", "how_to_apply": "",
+        "order_index": 0, "created_at": _now(), "updated_at": _now(),
+    }, attrs)
+
+
+class FakeMCP:
+    """Stand-in for the FastMCP server a tool module's ``register(mcp)`` is
+    handed: records the ``name=`` of every ``@mcp.tool(...)`` registration in
+    ``names`` and leaves the function untouched, so a test can assert which
+    tools a module exposes."""
+
+    def __init__(self) -> None:
+        self.names: list[str] = []
+
+    def tool(self, name=None):
+        self.names.append(name)
+        return lambda fn: fn
+
+
+def loc(path: str = "", repo: str = "", symbol: str = "") -> dict:
+    """One snippet location, in the shape the record stores."""
+    return {"repo": repo, "path": path, "symbol": symbol}
+
+
+def design_token_stub(name, value_by_mode, group_name=None, purpose=None,
+                      order_index=0, supersedes=None) -> SimpleNamespace:
+    """A design-token row as the cascade / stylesheet code reads it."""
+    return SimpleNamespace(
+        name=name, value_by_mode=value_by_mode, group_name=group_name,
+        purpose=purpose, order_index=order_index, supersedes=supersedes or [],
+    )
@@ -5,7 +5,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest

 from scribe.services.api_keys import (
-    _hash_key,
+    hash_token,
    _key_prefix,
    generate_key,
    create_api_key,
@@ -13,6 +13,7 @@ from scribe.services.api_keys import (
    revoke_api_key,
    lookup_key,
 )
+from tests.helpers import make_mock_session


 def test_generate_key_format():
@@ -28,7 +29,7 @@ def test_generate_key_uniqueness():

 def test_hash_key_is_sha256():
    key = "fmcp_testkey"
-    h = _hash_key(key)
+    h = hash_token(key)
    expected = hashlib.sha256(key.encode()).hexdigest()
    assert h == expected

@@ -45,9 +46,7 @@ async def test_create_api_key_returns_full_key():
    mock_key_obj.to_dict.return_value = {"id": 1, "name": "test", "scope": "read", "key_prefix": "fmcp_xxx"}

    with patch("scribe.services.api_keys.async_session") as mock_session_ctx:
-        mock_session = AsyncMock()
-        mock_session.__aenter__ = AsyncMock(return_value=mock_session)
-        mock_session.__aexit__ = AsyncMock(return_value=False)
+        mock_session = make_mock_session()
        mock_session.add = MagicMock()
        mock_session.commit = AsyncMock()
        mock_session.refresh = AsyncMock(side_effect=lambda obj: None)
@@ -67,9 +66,7 @@ async def test_create_api_key_returns_full_key():
@pytest.mark.asyncio
 async def test_lookup_key_returns_none_for_unknown():
    with patch("scribe.services.api_keys.async_session") as mock_session_ctx:
-        mock_session = AsyncMock()
-        mock_session.__aenter__ = AsyncMock(return_value=mock_session)
-        mock_session.__aexit__ = AsyncMock(return_value=False)
+        mock_session = make_mock_session()
        mock_result = MagicMock()
        mock_result.scalars.return_value.first.return_value = None
        mock_session.execute = AsyncMock(return_value=mock_result)
@@ -82,7 +79,7 @@ async def test_lookup_key_returns_none_for_unknown():

 def test_hash_key_deterministic():
    key = "fmcp_some_test_key_value"
-    assert _hash_key(key) == _hash_key(key)
+    assert hash_token(key) == hash_token(key)


@pytest.mark.asyncio
@@ -7,6 +7,7 @@ own import-free module — see services/design_cascade.py.
 from types import SimpleNamespace

 from scribe.services.design_cascade import ancestry, resolve_tokens, would_cycle
+from tests.helpers import design_token_stub


 # --- ancestry ---------------------------------------------------------------
@@ -102,14 +103,6 @@ def test_the_guard_survives_a_hierarchy_that_is_already_corrupt():
 # because resolve_tokens is pure and duck-typed — which is the whole reason it
 # lives here rather than inside the service.

-def _token(name, value_by_mode, group_name=None, purpose=None, order_index=0,
-           supersedes=None):
-    return SimpleNamespace(
-        name=name, value_by_mode=value_by_mode, group_name=group_name,
-        purpose=purpose, order_index=order_index, supersedes=supersedes or [],
-    )
-
-
 # A family (1) and an app inheriting from it (2) — the shape the model exists for.
 FAMILY, APP = 1, 2
 PARENTS = {FAMILY: None, APP: FAMILY}
@@ -124,7 +117,7 @@ def test_a_system_with_no_tokens_of_its_own_inherits_the_whole_family_set():
    and the state every app system starts in."""
    resolved = resolve_tokens(
        APP, PARENTS,
-        {FAMILY: [_token("--fs-obsidian", {"base": "#14171a"})], APP: []},
+        {FAMILY: [design_token_stub(name="--fs-obsidian", value_by_mode={"base": "#14171a"})], APP: []},
    )
    assert [t.name for t in resolved] == ["--fs-obsidian"]
    assert resolved[0].value_by_mode == {"base": "#14171a"}
@@ -138,8 +131,8 @@ def test_the_deepest_system_wins_and_says_what_it_overrode():
    resolved = _by_name(resolve_tokens(
        APP, PARENTS,
        {
-            FAMILY: [_token("--fs-accent", {"base": "#6b2118"})],
-            APP: [_token("--fs-accent", {"base": "#5b4a8a"})],
+            FAMILY: [design_token_stub(name="--fs-accent", value_by_mode={"base": "#6b2118"})],
+            APP: [design_token_stub(name="--fs-accent", value_by_mode={"base": "#5b4a8a"})],
        },
    ))
    accent = resolved["--fs-accent"]
@@ -158,8 +151,8 @@ def test_overriding_one_mode_leaves_the_others_inherited():
    resolved = _by_name(resolve_tokens(
        APP, PARENTS,
        {
-            FAMILY: [_token("--fs-accent", {"base": "#34a877", "dark": "#34a877"})],
-            APP: [_token("--fs-accent", {"base": "#15803d"})],
+            FAMILY: [design_token_stub(name="--fs-accent", value_by_mode={"base": "#34a877", "dark": "#34a877"})],
+            APP: [design_token_stub(name="--fs-accent", value_by_mode={"base": "#15803d"})],
        },
    ))
    accent = resolved["--fs-accent"]
@@ -172,7 +165,7 @@ def test_a_token_only_the_app_defines_is_not_an_override():
    labelled both "overridden here" would misdescribe the first."""
    resolved = _by_name(resolve_tokens(
        APP, PARENTS,
-        {FAMILY: [], APP: [_token("--fs-editor-caret", {"base": "#5b4a8a"})]},
+        {FAMILY: [], APP: [design_token_stub(name="--fs-editor-caret", value_by_mode={"base": "#5b4a8a"})]},
    ))
    caret = resolved["--fs-editor-caret"]
    assert caret.origin_by_mode == {"base": APP}
@@ -183,8 +176,8 @@ def test_is_overridden_in_is_true_only_for_the_system_that_shadowed():
    resolved = _by_name(resolve_tokens(
        APP, PARENTS,
        {
-            FAMILY: [_token("--fs-accent", {"base": "#6b2118"})],
-            APP: [_token("--fs-accent", {"base": "#5b4a8a"})],
+            FAMILY: [design_token_stub(name="--fs-accent", value_by_mode={"base": "#6b2118"})],
+            APP: [design_token_stub(name="--fs-accent", value_by_mode={"base": "#5b4a8a"})],
        },
    ))
    accent = resolved["--fs-accent"]
@@ -198,9 +191,9 @@ def test_three_levels_stack_nearest_first():
    resolved = _by_name(resolve_tokens(
        3, parents,
        {
-            1: [_token("--fs-bg", {"base": "a"})],
-            2: [_token("--fs-bg", {"base": "b"})],
-            3: [_token("--fs-bg", {"base": "c"})],
+            1: [design_token_stub(name="--fs-bg", value_by_mode={"base": "a"})],
+            2: [design_token_stub(name="--fs-bg", value_by_mode={"base": "b"})],
+            3: [design_token_stub(name="--fs-bg", value_by_mode={"base": "c"})],
        },
    ))
    bg = resolved["--fs-bg"]
@@ -214,8 +207,8 @@ def test_resolving_the_family_itself_ignores_its_children():
    resolved = _by_name(resolve_tokens(
        FAMILY, PARENTS,
        {
-            FAMILY: [_token("--fs-accent", {"base": "#6b2118"})],
-            APP: [_token("--fs-accent", {"base": "#5b4a8a"})],
+            FAMILY: [design_token_stub(name="--fs-accent", value_by_mode={"base": "#6b2118"})],
+            APP: [design_token_stub(name="--fs-accent", value_by_mode={"base": "#5b4a8a"})],
        },
    ))
    assert resolved["--fs-accent"].value_by_mode == {"base": "#6b2118"}
@@ -226,7 +219,7 @@ def test_value_for_falls_back_to_the_base_mode():
    "dark" must yield that rather than nothing — the read rule the storage shape
    implies."""
    resolved = _by_name(resolve_tokens(
-        FAMILY, PARENTS, {FAMILY: [_token("--fs-radius-md", {"base": "8px"})]},
+        FAMILY, PARENTS, {FAMILY: [design_token_stub(name="--fs-radius-md", value_by_mode={"base": "8px"})]},
    ))
    radius = resolved["--fs-radius-md"]
    assert radius.value_for("dark") == "8px"
@@ -236,7 +229,7 @@ def test_value_for_falls_back_to_the_base_mode():
 def test_value_for_prefers_an_explicit_mode_over_the_fallback():
    resolved = _by_name(resolve_tokens(
        FAMILY, PARENTS,
-        {FAMILY: [_token("--fs-bg", {"base": "#f7f5ef", "dark": "#14171a"})]},
+        {FAMILY: [design_token_stub(name="--fs-bg", value_by_mode={"base": "#f7f5ef", "dark": "#14171a"})]},
    ))
    assert resolved["--fs-bg"].value_for("dark") == "#14171a"

@@ -248,11 +241,8 @@ def test_metadata_is_inherited_when_the_override_leaves_it_blank():
    resolved = _by_name(resolve_tokens(
        APP, PARENTS,
        {
-            FAMILY: [_token(
-                "--fs-obsidian", {"base": "#14171a"},
-                group_name="surface", purpose="page bg, deepest surface",
-            )],
-            APP: [_token("--fs-obsidian", {"base": "#101317"})],
+            FAMILY: [design_token_stub(name="--fs-obsidian", value_by_mode={"base": "#14171a"}, group_name="surface", purpose="page bg, deepest surface")],
+            APP: [design_token_stub(name="--fs-obsidian", value_by_mode={"base": "#101317"})],
        },
    ))
    obsidian = resolved["--fs-obsidian"]
@@ -265,8 +255,8 @@ def test_an_override_that_states_metadata_wins_it_too():
    resolved = _by_name(resolve_tokens(
        APP, PARENTS,
        {
-            FAMILY: [_token("--fs-x", {"base": "a"}, purpose="family says")],
-            APP: [_token("--fs-x", {"base": "b"}, purpose="app says")],
+            FAMILY: [design_token_stub(name="--fs-x", value_by_mode={"base": "a"}, purpose="family says")],
+            APP: [design_token_stub(name="--fs-x", value_by_mode={"base": "b"}, purpose="app says")],
        },
    ))
    assert resolved["--fs-x"].purpose == "app says"
@@ -279,8 +269,8 @@ def test_an_override_at_default_order_keeps_the_familys_position():
    resolved = _by_name(resolve_tokens(
        APP, PARENTS,
        {
-            FAMILY: [_token("--fs-x", {"base": "a"}, order_index=7)],
-            APP: [_token("--fs-x", {"base": "b"})],
+            FAMILY: [design_token_stub(name="--fs-x", value_by_mode={"base": "a"}, order_index=7)],
+            APP: [design_token_stub(name="--fs-x", value_by_mode={"base": "b"})],
        },
    ))
    assert resolved["--fs-x"].order_index == 7
@@ -290,10 +280,10 @@ def test_the_effective_set_is_ordered_by_group_then_position_with_ungrouped_last
    resolved = resolve_tokens(
        FAMILY, PARENTS,
        {FAMILY: [
-            _token("--fs-z", {"base": "1"}),                                  # ungrouped
-            _token("--fs-b", {"base": "2"}, group_name="text", order_index=1),
-            _token("--fs-a", {"base": "3"}, group_name="surface", order_index=2),
-            _token("--fs-c", {"base": "4"}, group_name="surface", order_index=1),
+            design_token_stub(name="--fs-z", value_by_mode={"base": "1"}),                                  # ungrouped
+            design_token_stub(name="--fs-b", value_by_mode={"base": "2"}, group_name="text", order_index=1),
+            design_token_stub(name="--fs-a", value_by_mode={"base": "3"}, group_name="surface", order_index=2),
+            design_token_stub(name="--fs-c", value_by_mode={"base": "4"}, group_name="surface", order_index=1),
        ]},
    )
    assert [t.name for t in resolved] == ["--fs-c", "--fs-a", "--fs-b", "--fs-z"]
@@ -306,7 +296,7 @@ def test_resolution_terminates_on_a_corrupt_hierarchy():
    parents = {1: 2, 2: 1}
    resolved = _by_name(resolve_tokens(
        1, parents,
-        {1: [_token("--fs-a", {"base": "one"})], 2: [_token("--fs-b", {"base": "two"})]},
+        {1: [design_token_stub(name="--fs-a", value_by_mode={"base": "one"})], 2: [design_token_stub(name="--fs-b", value_by_mode={"base": "two"})]},
    ))
    assert set(resolved) == {"--fs-a", "--fs-b"}
    # Each system contributes exactly once, not endlessly.
@@ -326,8 +316,8 @@ def test_supersedes_is_inherited_when_the_override_is_silent_about_it():
    resolved = _by_name(resolve_tokens(
        APP, PARENTS,
        {
-            FAMILY: [_token("--fs-text", {"base": "#e8e4d8"}, supersedes=["#fff", "#ffffff"])],
-            APP: [_token("--fs-text", {"base": "#f0ece0"})],
+            FAMILY: [design_token_stub(name="--fs-text", value_by_mode={"base": "#e8e4d8"}, supersedes=["#fff", "#ffffff"])],
+            APP: [design_token_stub(name="--fs-text", value_by_mode={"base": "#f0ece0"})],
        },
    ))
    text = resolved["--fs-text"]
@@ -341,8 +331,8 @@ def test_an_override_that_states_its_own_supersedes_replaces_the_list():
    resolved = _by_name(resolve_tokens(
        APP, PARENTS,
        {
-            FAMILY: [_token("--fs-text", {"base": "a"}, supersedes=["#fff", "#ffffff"])],
-            APP: [_token("--fs-text", {"base": "b"}, supersedes=["#fff"])],
+            FAMILY: [design_token_stub(name="--fs-text", value_by_mode={"base": "a"}, supersedes=["#fff", "#ffffff"])],
+            APP: [design_token_stub(name="--fs-text", value_by_mode={"base": "b"}, supersedes=["#fff"])],
        },
    ))
    assert resolved["--fs-text"].supersedes == ("#fff",)
@@ -352,7 +342,7 @@ def test_a_token_that_supersedes_nothing_resolves_to_an_empty_tuple():
    """Most tokens replace nothing. That has to be an empty sequence rather than
    None, so no caller has to test for two kinds of nothing."""
    resolved = _by_name(resolve_tokens(
-        FAMILY, PARENTS, {FAMILY: [_token("--fs-radius-md", {"base": "8px"})]},
+        FAMILY, PARENTS, {FAMILY: [design_token_stub(name="--fs-radius-md", value_by_mode={"base": "8px"})]},
    ))
    assert resolved["--fs-radius-md"].supersedes == ()

@@ -360,7 +350,7 @@ def test_a_token_that_supersedes_nothing_resolves_to_an_empty_tuple():
 def test_supersedes_survives_serialisation_as_a_list():
    resolved = _by_name(resolve_tokens(
        FAMILY, PARENTS,
-        {FAMILY: [_token("--fs-text", {"base": "#e8e4d8"}, supersedes=["#fff"])]},
+        {FAMILY: [design_token_stub(name="--fs-text", value_by_mode={"base": "#e8e4d8"}, supersedes=["#fff"])]},
    ))
    assert resolved["--fs-text"].to_dict()["supersedes"] == ["#fff"]

@@ -372,7 +362,7 @@ def test_the_superseded_literal_need_not_match_the_tokens_own_value():
    it was turned around."""
    resolved = _by_name(resolve_tokens(
        FAMILY, PARENTS,
-        {FAMILY: [_token("--fs-text", {"base": "#e8e4d8"}, supersedes=["#fff"])]},
+        {FAMILY: [design_token_stub(name="--fs-text", value_by_mode={"base": "#e8e4d8"}, supersedes=["#fff"])]},
    ))
    text = resolved["--fs-text"]
    assert text.value_by_mode["base"] not in text.supersedes
@@ -404,7 +394,7 @@ def test_rationale_cascades_like_purpose_and_is_a_different_question():
                rationale="equals Moss, aligned by design",
                order_index=0, supersedes=[],
            )],
-            APP: [_token("--fs-success", {"base": "#3f5236"})],
+            APP: [design_token_stub(name="--fs-success", value_by_mode={"base": "#3f5236"})],
        },
    ))
    token = resolved["--fs-success"]
@@ -415,6 +405,6 @@ def test_rationale_cascades_like_purpose_and_is_a_different_question():

 def test_a_token_without_a_rationale_resolves_to_none():
    resolved = _by_name(resolve_tokens(
-        FAMILY, PARENTS, {FAMILY: [_token("--fs-x", {"base": "1px"})]},
+        FAMILY, PARENTS, {FAMILY: [design_token_stub(name="--fs-x", value_by_mode={"base": "1px"})]},
    ))
    assert resolved["--fs-x"].rationale is None
--- a/Show More
+++ b/Show More