Merge pull request 'Project inception — decide what a new project inherits (milestone 297)' (#124) from dev into main

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

README.md

@@ -4,7 +4,7 @@ A self-hosted work system-of-record for software projects, built to be driven by
 
 ## Features
 
-Notes and tasks with a Markdown editor, sub-tasks, milestones, issues, and kanban project workspaces. Stored processes, an engineering rulebook system, and semantic search with proactive knowledge-injection into Claude's context. A knowledge graph, per-user/group sharing, and a built-in MCP server (`/mcp`) plus a bundled Claude Code plugin so Claude can record and recall your work directly.
+Notes and tasks with a Markdown editor, sub-tasks, milestones, issues, and kanban project workspaces. Stored processes, an engineering rulebook system (with an inception step that decides what each project inherits), and semantic search with proactive knowledge-injection into Claude's context. A knowledge graph, per-user/group sharing, and a built-in MCP server (`/mcp`) plus a bundled Claude Code plugin so Claude can record and recall your work directly.
 
 ## Quick Start
 

alembic/versions/0082_repo_binding_ref.py

@@ -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")

alembic/versions/0083_code_shape_reason_code.py

@@ -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")

alembic/versions/0084_code_shape_uses.py

@@ -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 — e.g. a
+service function both conforming to the service-function convention and
+consuming 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")

alembic/versions/0085_project_inception.py

@@ -0,0 +1,74 @@
+"""Project inception: the decision record + always-on rulebook exclusions (milestone 297)
+
+Revision ID: 0085
+Revises: 0084
+Create Date: 2026-08-22
+
+`projects.inception` is the WHY a project inherits what it does — NULL until
+someone decides, at which point enter_project stops asking. The new
+association `project_rulebook_exclusions` is the opt-out of a whole always-on
+rulebook for one project (the sibling of the rule/topic suppressions).
+
+Backfill: every project that exists when this runs is stamped
+via="legacy" with its CURRENT standing (no exclusions, its subscriptions,
+its design_system_id, no seed) — so the ask fires only for projects created
+after the step shipped, and nothing a running install relies on changes.
+"""
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision = "0085"
+down_revision = "0084"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "projects",
+        sa.Column("inception", postgresql.JSONB(), nullable=True),
+    )
+    op.create_table(
+        "project_rulebook_exclusions",
+        sa.Column(
+            "project_id", sa.BigInteger(),
+            sa.ForeignKey("projects.id", ondelete="CASCADE"),
+            primary_key=True, nullable=False,
+        ),
+        sa.Column(
+            "rulebook_id", sa.BigInteger(),
+            sa.ForeignKey("rulebooks.id", ondelete="CASCADE"),
+            primary_key=True, nullable=False,
+        ),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True),
+            server_default=sa.text("now()"), nullable=False,
+        ),
+    )
+    # Legacy stamp: what each existing project inherits today, recorded as a
+    # decision so the inception ask does not fire on a project that has been
+    # running for months.
+    op.execute(sa.text("""
+        UPDATE projects p SET inception = jsonb_build_object(
+            'via', 'legacy',
+            'decided_at', to_jsonb(now()),
+            'decided_by', NULL,
+            'choices', jsonb_build_object(
+                'exclude_always_on_rulebooks', '[]'::jsonb,
+                'subscribe_rulebooks', COALESCE(
+                    (SELECT jsonb_agg(s.rulebook_id ORDER BY s.rulebook_id)
+                       FROM project_rulebook_subscriptions s
+                      WHERE s.project_id = p.id),
+                    '[]'::jsonb),
+                'design_system_id', to_jsonb(p.design_system_id),
+                'seed_systems', false
+            )
+        )
+        WHERE p.inception IS NULL
+    """))
+
+
+def downgrade() -> None:
+    op.drop_table("project_rulebook_exclusions")
+    op.drop_column("projects", "inception")

docs/api-reference.md

@@ -76,7 +76,9 @@ endpoint at `/mcp`, not these REST routes.
 | Method | Path | Description |
 |--------|------|-------------|
 | GET / POST | `/api/projects` | List (owned + shared) / create |
-| GET / PATCH / DELETE | `/api/projects/:id` | Read (with `milestone_summary`) / update / delete |
+| GET / PATCH / DELETE | `/api/projects/:id` | Read (with `milestone_summary`, `inception`) / update / delete |
+| POST | `/api/projects/:id/inception` | Record what the project inherits `{choices: {exclude_always_on_rulebooks, subscribe_rulebooks, design_system_id, seed_systems}}` (owner-only; `POST /api/projects` accepts the same under `inception`) |
+| GET | `/api/projects/:id/inception/defaults` | What binds if nobody decides — the inception card's payload |
 | GET | `/api/projects/:id/notes` | Notes + tasks in this project |
 | GET / POST | `/api/projects/:id/milestones` | List / create milestones |
 | GET / PATCH / DELETE | `/api/projects/:id/milestones/:mid` | Read / update / delete |
@@ -118,6 +120,7 @@ endpoint at `/mcp`, not these REST routes.
 | POST | `/api/projects/:id/rules` | Create a project-scoped rule |
 | POST / DELETE | `/api/projects/:id/suppressions/rules/:rid` | Suppress / unsuppress a rule |
 | POST / DELETE | `/api/projects/:id/suppressions/topics/:tid` | Suppress / unsuppress a topic |
+| POST / DELETE | `/api/projects/:id/exclusions/rulebooks/:rid` | Exclude / include an always-on rulebook for this project (inception) |
 
 ## Sharing
 

frontend/src/api/client.ts

@@ -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);

frontend/src/api/inception.ts

@@ -0,0 +1,42 @@
+/** Project inception (milestone 297): what a project was decided to inherit. */
+import { apiGet, apiPost } from "@/api/client";
+
+export interface InceptionChoices {
+  exclude_always_on_rulebooks: number[];
+  subscribe_rulebooks: number[];
+  design_system_id: number | null;
+  seed_systems: boolean;
+}
+
+export interface InceptionRecord {
+  decided_at: string;
+  decided_by: number | null;
+  via: "mcp" | "ui" | "legacy";
+  choices: InceptionChoices;
+}
+
+export interface InceptionDefaults {
+  always_on_rulebooks: { id: number; title: string }[];
+  other_rulebooks: { id: number; title: string }[];
+  excluded_always_on: { id: number; title: string }[];
+  subscribed_rulebooks: { id: number; title: string }[];
+  design_system_id: number | null;
+  design_systems: { id: number; title: string }[];
+  systems: number;
+}
+
+export interface InceptionDecision {
+  project_id: number;
+  inception: InceptionRecord;
+  effects: { excluded: number[]; subscribed: number[]; design_system_id: number | null; systems_seeded: string[] };
+}
+
+export const emptyChoices = (): InceptionChoices => ({
+  exclude_always_on_rulebooks: [], subscribe_rulebooks: [], design_system_id: null, seed_systems: false,
+});
+
+export const fetchInceptionDefaults = (projectId: number) =>
+  apiGet<InceptionDefaults>(`/api/projects/${projectId}/inception/defaults`);
+
+export const decideInception = (projectId: number, choices: InceptionChoices) =>
+  apiPost<InceptionDecision>(`/api/projects/${projectId}/inception`, { choices });

frontend/src/api/rulebooks.ts

@@ -71,6 +71,8 @@ export interface ApplicableRules {
   }[];
   truncated: boolean;
   subscribed_rulebooks: { id: number; title: string }[];
+  /** Always-on rulebooks this project opted out of at inception (milestone 297). */
+  excluded_always_on: { id: number; title: string }[];
 }
 
 // ── Rulebooks ───────────────────────────────────────────────────────
@@ -181,3 +183,14 @@ export async function suppressTopicForProject(projectId: number, topicId: number
 export async function unsuppressTopicForProject(projectId: number, topicId: number): Promise<void> {
   return apiDelete(`/api/projects/${projectId}/suppressions/topics/${topicId}`);
 }
+
+// ── Always-on exclusions (milestone 297) ────────────────────────────────────
+
+export async function excludeAlwaysOnRulebook(projectId: number, rulebookId: number): Promise<void> {
+  await apiPost(`/api/projects/${projectId}/exclusions/rulebooks/${rulebookId}`, {});
+}
+
+export async function includeAlwaysOnRulebook(projectId: number, rulebookId: number): Promise<void> {
+  await apiDelete(`/api/projects/${projectId}/exclusions/rulebooks/${rulebookId}`);
+}
+

frontend/src/assets/auth-shared.css

@@ -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);
+}

frontend/src/assets/components.css

@@ -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);
+}

frontend/src/assets/editor-shared.css

@@ -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;

frontend/src/components/HistoryPanel.vue

@@ -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>
 

frontend/src/components/InceptionCard.vue

@@ -0,0 +1,189 @@
+<script setup lang="ts">
+/**
+ * The inception form (milestone 297): "what does this project inherit?"
+ *
+ * Two homes, one component. mode="create" rides the New-project modal's
+ * second step and only emits the choices (the project does not exist yet);
+ * mode="decide" sits on ProjectView for an undecided project, loads that
+ * project's current defaults, and records the decision itself.
+ */
+import { computed, onMounted, ref, watch } from "vue";
+import { apiErrorMessage } from "@/api/client";
+import { fetchDesignSystems } from "@/api/designSystems";
+import {
+  decideInception, emptyChoices, fetchInceptionDefaults,
+  type InceptionChoices, type InceptionDecision, type InceptionDefaults,
+} from "@/api/inception";
+import { listRulebooks } from "@/api/rulebooks";
+
+const props = withDefaults(defineProps<{
+  mode: "create" | "decide";
+  projectId?: number;
+  choices?: InceptionChoices;
+}>(), { projectId: 0, choices: undefined });
+
+const emit = defineEmits<{
+  "update:choices": [value: InceptionChoices];
+  decided: [decision: InceptionDecision];
+}>();
+
+const local = ref<InceptionChoices>(props.choices ? { ...props.choices } : emptyChoices());
+const alwaysOn = ref<{ id: number; title: string }[]>([]);
+const others = ref<{ id: number; title: string }[]>([]);
+const designSystems = ref<{ id: number; title: string }[]>([]);
+const systemsCount = ref(0);
+const loading = ref(true);
+const saving = ref(false);
+const error = ref("");
+
+function emitChoices() {
+  emit("update:choices", { ...local.value });
+}
+watch(local, emitChoices, { deep: true });
+
+async function load() {
+  loading.value = true;
+  error.value = "";
+  try {
+    if (props.mode === "decide" && props.projectId) {
+      const d: InceptionDefaults = await fetchInceptionDefaults(props.projectId);
+      alwaysOn.value = d.always_on_rulebooks;
+      others.value = d.other_rulebooks;
+      designSystems.value = d.design_systems;
+      systemsCount.value = d.systems;
+      // Start from what stands today so "record" without changes is a true inherit-all.
+      local.value = {
+        exclude_always_on_rulebooks: d.excluded_always_on.map((r) => r.id),
+        subscribe_rulebooks: d.subscribed_rulebooks.map((r) => r.id),
+        design_system_id: d.design_system_id,
+        seed_systems: false,
+      };
+    } else {
+      const [rulebooks, ds] = await Promise.all([listRulebooks(), fetchDesignSystems()]);
+      alwaysOn.value = rulebooks.filter((r) => r.always_on).map((r) => ({ id: r.id, title: r.title }));
+      others.value = rulebooks.filter((r) => !r.always_on).map((r) => ({ id: r.id, title: r.title }));
+      designSystems.value = ds.design_systems.map((d) => ({ id: d.id, title: d.title }));
+    }
+  } catch (e: unknown) {
+    error.value = apiErrorMessage(e, "Could not load what this project could inherit");
+  } finally {
+    loading.value = false;
+  }
+}
+
+function inherits(id: number): boolean {
+  return !local.value.exclude_always_on_rulebooks.includes(id);
+}
+function toggleInherit(id: number) {
+  const list = local.value.exclude_always_on_rulebooks;
+  local.value.exclude_always_on_rulebooks = list.includes(id) ? list.filter((x) => x !== id) : [...list, id];
+}
+function subscribed(id: number): boolean {
+  return local.value.subscribe_rulebooks.includes(id);
+}
+function toggleSubscribe(id: number) {
+  const list = local.value.subscribe_rulebooks;
+  local.value.subscribe_rulebooks = list.includes(id) ? list.filter((x) => x !== id) : [...list, id];
+}
+
+const nothingToDecide = computed(
+  () => !alwaysOn.value.length && !others.value.length && !designSystems.value.length,
+);
+
+async function record() {
+  if (!props.projectId) return;
+  saving.value = true;
+  error.value = "";
+  try {
+    const decision = await decideInception(props.projectId, local.value);
+    emit("decided", decision);
+  } catch (e: unknown) {
+    error.value = apiErrorMessage(e, "Could not record the decision");
+  } finally {
+    saving.value = false;
+  }
+}
+
+onMounted(load);
+</script>
+
+<template>
+  <section class="inception" aria-labelledby="inception-title">
+    <h3 id="inception-title" class="inception-title">What does this project inherit?</h3>
+    <p class="inception-lede">
+      A project's inheritance is a decision, not a default. Until it is recorded,
+      every always-on rulebook binds, nothing is subscribed, and there is no design
+      system or Systems.
+    </p>
+    <p v-if="loading" class="inception-muted">Loading…</p>
+    <p v-else-if="error" class="error-msg">{{ error }}</p>
+    <template v-else>
+      <div v-if="alwaysOn.length" class="inception-group">
+        <h4>Always-on rulebooks</h4>
+        <p class="inception-muted">Checked = inherits. Uncheck to exclude a rulebook for this project only.</p>
+        <label v-for="rb in alwaysOn" :key="rb.id" class="inception-choice">
+          <input type="checkbox" :checked="inherits(rb.id)" @change="toggleInherit(rb.id)" />
+          <span>{{ rb.title }}</span>
+        </label>
+      </div>
+      <div v-if="others.length" class="inception-group">
+        <h4>Subscribe to rulebooks</h4>
+        <label v-for="rb in others" :key="rb.id" class="inception-choice">
+          <input type="checkbox" :checked="subscribed(rb.id)" @change="toggleSubscribe(rb.id)" />
+          <span>{{ rb.title }}</span>
+        </label>
+      </div>
+      <div class="inception-group">
+        <h4>Design system</h4>
+        <select v-model="local.design_system_id" class="inception-select" aria-label="Design system">
+          <option :value="null">None</option>
+          <option v-for="ds in designSystems" :key="ds.id" :value="ds.id">{{ ds.title }}</option>
+        </select>
+      </div>
+      <div class="inception-group">
+        <label class="inception-choice">
+          <input type="checkbox" v-model="local.seed_systems" :disabled="systemsCount > 0" />
+          <span>
+            Seed the standard starter Systems (CI &amp; Release, Auth &amp; Access, Data Model &amp; Storage, …)
+            <em v-if="systemsCount > 0" class="inception-muted"> — this project already has {{ systemsCount }}</em>
+          </span>
+        </label>
+      </div>
+      <p v-if="nothingToDecide" class="inception-muted">
+        Nothing to inherit yet on this install — recording still settles the question.
+      </p>
+      <div v-if="mode === 'decide'" class="inception-actions">
+        <button class="btn-primary" :disabled="saving" @click="record">
+          {{ saving ? "Recording…" : "Record decision" }}
+        </button>
+      </div>
+    </template>
+  </section>
+</template>
+
+<style scoped>
+.inception {
+  background: var(--fs-surface-raised);
+  border: 1px solid var(--fs-border-color);
+  border-radius: var(--fs-radius-lg);
+  padding: 1.25rem 1.5rem;
+  margin-bottom: 1.5rem;
+}
+.inception-title { margin: 0 0 0.35rem; font-size: 1.05rem; }
+.inception-lede { margin: 0 0 1rem; color: var(--fs-text-secondary); font-size: 0.9rem; }
+.inception-muted { color: var(--fs-text-tertiary); font-size: 0.85rem; margin: 0 0 0.35rem; }
+.inception-group { margin-bottom: 1rem; }
+.inception-group h4 { margin: 0 0 0.35rem; font-size: 0.9rem; font-weight: 500; }
+.inception-choice { display: flex; align-items: flex-start; gap: 0.5rem; font-size: 0.9rem; margin: 0.25rem 0; }
+.inception-choice input { margin-top: 0.2rem; accent-color: var(--fs-accent); }
+.inception-select {
+  padding: 0.45rem 0.7rem;
+  border: 1px solid var(--fs-border-color);
+  border-radius: var(--fs-radius-sm);
+  background: var(--fs-surface-page);
+  color: var(--fs-text-primary);
+  font-size: 0.9rem;
+}
+.inception-actions { display: flex; justify-content: flex-end; margin-top: 0.5rem; }
+.error-msg { color: var(--fs-error); font-size: 0.9rem; }
+</style>

frontend/src/components/SystemsSection.vue

@@ -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>

frontend/src/components/TaskLogSection.vue

@@ -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>

frontend/src/components/WorkspaceNoteEditor.vue

@@ -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

frontend/src/components/WorkspaceTaskPanel.vue

@@ -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>

frontend/src/components/rules/ProjectRulesTab.vue

@@ -2,10 +2,18 @@
 import { ref, onMounted, watch } from "vue";
 import { useRouter } from "vue-router";
 import {
-  getProjectApplicableRules, subscribeProject, unsubscribeProject,
-  listRulebooks, getRule, createProjectRule, deleteRule,
-  suppressRuleForProject, unsuppressRuleForProject,
-  suppressTopicForProject, unsuppressTopicForProject,
+  getProjectApplicableRules,
+  subscribeProject,
+  unsubscribeProject,
+  listRulebooks,
+  getRule,
+  createProjectRule,
+  deleteRule,
+  suppressRuleForProject,
+  unsuppressRuleForProject,
+  suppressTopicForProject,
+  unsuppressTopicForProject,
+  includeAlwaysOnRulebook,
 } from "@/api/rulebooks";
 import type { ApplicableRules, Rulebook } from "@/api/rulebooks";
 
@@ -35,6 +43,11 @@ async function subscribe(rulebookId: number) {
   await load();
 }
 
+async function includeBack(rulebookId: number) {
+  await includeAlwaysOnRulebook(props.projectId, rulebookId);
+  await load();
+}
+
 async function unsubscribe(rulebookId: number) {
   if (!confirm("Unsubscribe from this rulebook for this project?")) return;
   await unsubscribeProject(props.projectId, rulebookId);
@@ -172,6 +185,17 @@ watch(() => props.projectId, load);
       </div>
     </section>
 
+    <section v-if="applicable.excluded_always_on?.length" class="excluded">
+      <h3>Excluded always-on rulebooks</h3>
+      <p class="excluded-note">Opted out at inception — these do not bind this project.</p>
+      <div class="chips">
+        <span v-for="rb in applicable.excluded_always_on" :key="rb.id" class="chip chip-excluded">
+          <a @click="openInRulesView(rb.id)">{{ rb.title }}</a>
+          <button class="chip-remove" @click="includeBack(rb.id)" aria-label="Include again" title="Include again">↩</button>
+        </span>
+      </div>
+    </section>
+
     <section class="project-rules">
       <div class="section-head">
         <h3>Project rules</h3>
@@ -321,6 +345,9 @@ watch(() => props.projectId, load);
 </template>
 
 <style scoped>
+.excluded-note { margin: 0 0 0.5rem; color: var(--fs-text-tertiary); font-size: 0.85rem; }
+.chip-excluded { opacity: 0.8; text-decoration: line-through; }
+.chip-excluded .chip-remove { text-decoration: none; }
 .rules-tab { padding: 1rem; }
 h3 {
   font-size: 0.9em; opacity: 0.7; text-transform: uppercase; letter-spacing: 0.05em;

frontend/src/composables/useRelativeTime.ts

@@ -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" });
+}

frontend/src/utils/dateFormat.ts

@@ -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",
+  });
 }

frontend/src/views/ForgotPasswordView.vue

@@ -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" />

frontend/src/views/LoginView.vue

@@ -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;

frontend/src/views/LogsView.vue

@@ -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 }}

frontend/src/views/ProjectListView.vue

@@ -1,7 +1,9 @@
 <script setup lang="ts">
 import { ref, computed, onMounted } from "vue";
 import { useRouter } from "vue-router";
-import { apiGet, apiPost } from "@/api/client";
+import { apiGet, apiPost, apiErrorMessage } from "@/api/client";
+import { emptyChoices, type InceptionChoices } from "@/api/inception";
+import InceptionCard from "@/components/InceptionCard.vue";
 import { useToastStore } from "@/stores/toast";
 import { milestoneColor } from "@/utils/palette";
 
@@ -47,6 +49,9 @@ const newTitle = ref("");
 const newDescription = ref("");
 const newGoal = ref("");
 const creating = ref(false);
+// Step 2 of the modal (milestone 297): what the new project inherits.
+const modalStep = ref<1 | 2>(1);
+const newInception = ref<InceptionChoices>(emptyChoices());
 
 const filteredProjects = computed(() => {
   if (activeTab.value === "all") return projects.value;
@@ -73,6 +78,8 @@ function openNewProjectModal() {
   newTitle.value = "";
   newDescription.value = "";
   newGoal.value = "";
+  modalStep.value = 1;
+  newInception.value = emptyChoices();
   showNewProjectModal.value = true;
 }
 
@@ -88,13 +95,15 @@ async function createProject() {
       title: newTitle.value.trim(),
       description: newDescription.value.trim() || undefined,
       goal: newGoal.value.trim() || undefined,
+      // The decision rides the create: a project made here is never undecided.
+      inception: newInception.value,
     });
     projects.value.unshift(project);
     showNewProjectModal.value = false;
     toast.show("Project created");
     router.push(`/projects/${project.id}`);
-  } catch {
-    toast.show("Failed to create project", "error");
+  } catch (e: unknown) {
+    toast.show(apiErrorMessage(e, "Failed to create project"), "error");
   } finally {
     creating.value = false;
   }
@@ -266,8 +275,9 @@ function overallPct(project: Project): { total: number; pct: number } {
     <teleport to="body">
       <div v-if="showNewProjectModal" class="modal-overlay" @click.self="closeModal">
         <div class="modal-card">
-          <h3 class="modal-title">New Project</h3>
-          <div class="modal-field">
+          <h3 class="modal-title">{{ modalStep === 1 ? "New Project" : "New Project — what it inherits" }}</h3>
+          <InceptionCard v-if="modalStep === 2" mode="create" v-model:choices="newInception" />
+          <div v-if="modalStep === 1" class="modal-field">
             <label>Title <span class="required">*</span></label>
             <input
               v-model="newTitle"
@@ -275,11 +285,11 @@ function overallPct(project: Project): { total: number; pct: number } {
               class="modal-input"
               placeholder="Project title"
               autofocus
-              @keydown.enter="createProject"
+              @keydown.enter="modalStep = 2"
               @keydown.escape="closeModal"
             />
           </div>
-          <div class="modal-field">
+          <div v-if="modalStep === 1" class="modal-field">
             <label>Goal</label>
             <input
               v-model="newGoal"
@@ -289,7 +299,7 @@ function overallPct(project: Project): { total: number; pct: number } {
               @keydown.escape="closeModal"
             />
           </div>
-          <div class="modal-field">
+          <div v-if="modalStep === 1" class="modal-field">
             <label>Description</label>
             <textarea
               v-model="newDescription"
@@ -301,7 +311,17 @@ function overallPct(project: Project): { total: number; pct: number } {
           </div>
           <div class="modal-actions">
             <button class="modal-btn" @click="closeModal">Cancel</button>
+            <button v-if="modalStep === 2" class="modal-btn" @click="modalStep = 1">Back</button>
             <button
+              v-if="modalStep === 1"
+              class="modal-btn modal-btn-primary"
+              @click="modalStep = 2"
+              :disabled="!newTitle.trim()"
+            >
+              Next
+            </button>
+            <button
+              v-else
               class="modal-btn modal-btn-primary"
               @click="createProject"
               :disabled="!newTitle.trim() || creating"
@@ -559,24 +579,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 +622,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 {

frontend/src/views/ProjectView.vue

@@ -11,6 +11,9 @@ import ShareDialog from "@/components/ShareDialog.vue";
 import ProjectDesignTab from "@/components/ProjectDesignTab.vue";
 import ProjectRulesTab from "@/components/rules/ProjectRulesTab.vue";
 import SystemsSection from "@/components/SystemsSection.vue";
+import InceptionCard from "@/components/InceptionCard.vue";
+import { fmtDate } from "@/utils/dateFormat";
+import type { InceptionDecision, InceptionRecord } from "@/api/inception";
 import {
   fetchDesignSystems,
   setProjectDesignSystem,
@@ -50,6 +53,7 @@ interface Project {
   color: string | null;
   design_system_id: number | null;
   forge_connection_id: number | null;
+  inception?: InceptionRecord | null;
   permission?: string;
   created_at: string;
   updated_at: string;
@@ -75,6 +79,12 @@ interface NoteItem {
 const route = useRoute();
 const router = useRouter();
 const toast = useToastStore();
+
+function onInceptionDecided(decision: InceptionDecision) {
+  if (project.value) project.value.inception = decision.inception;
+  toast.show("Inheritance recorded");
+  void loadProject();
+}
 const tasksStore = useTasksStore();
 
 const project = ref<Project | null>(null);
@@ -695,6 +705,26 @@ async function confirmDelete() {
         </p>
       </div>
 
+      <!-- Inception (milestone 297): the owner of an undecided project is asked
+           what it inherits; once recorded, one line says what was decided. -->
+      <InceptionCard
+        v-if="project.inception == null && isProjectOwner"
+        mode="decide"
+        :project-id="projectId"
+        @decided="onInceptionDecided"
+      />
+      <p v-else-if="project.inception" class="inception-line">
+        Inheritance decided {{ fmtDate(project.inception.decided_at) }} via {{ project.inception.via }}
+        <template v-if="project.inception.choices.exclude_always_on_rulebooks.length">
+          · excludes {{ project.inception.choices.exclude_always_on_rulebooks.length }} always-on rulebook(s)
+        </template>
+        <template v-if="project.inception.choices.subscribe_rulebooks.length">
+          · subscribes {{ project.inception.choices.subscribe_rulebooks.length }}
+        </template>
+        · design system {{ project.inception.choices.design_system_id ? "#" + project.inception.choices.design_system_id : "none" }}
+        <template v-if="project.inception.choices.seed_systems"> · Systems seeded</template>
+      </p>
+
       <!-- Summary stat chips -->
       <div v-if="project.summary" class="summary-stats">
         <div class="stat-chip stat-todo">
@@ -754,7 +784,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">
@@ -1197,6 +1227,7 @@ async function confirmDelete() {
   min-width: 200px;
 }
 
+.inception-line { margin: 0 0 1rem; color: var(--fs-text-secondary); font-size: 0.85rem; }
 .project-title-input {
   flex: 1;
   font-size: 1.75rem;
@@ -1815,31 +1846,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; } }

frontend/src/views/RegisterInviteView.vue

@@ -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" />

frontend/src/views/RegisterView.vue

@@ -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" />

frontend/src/views/ResetPasswordView.vue

@@ -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" />

frontend/src/views/SettingsView.vue

@@ -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>

frontend/src/views/SnippetListView.vue

@@ -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 {

frontend/src/views/UserManagementView.vue

@@ -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>

plugin/.claude-plugin/plugin.json

@@ -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.38",
   "author": { "name": "Bryan Van Deusen" },
   "mcpServers": {
     "scribe": {

plugin/skills/shape-accounting/SKILL.md

@@ -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

plugin/skills/using-scribe/SKILL.md

@@ -120,6 +120,28 @@ bound — confine the session to it:
 - If something clearly belongs to a *different* project, say so and **ask before
   switching** — never silently operate cross-project.
 
+## Starting a project: decide what it inherits
+
+A project's inheritance is a **decision, not a default**. Before
+`create_project`, ask the operator the four inception questions and pass the
+answers — never create a project bare by default:
+
+- which **always-on rulebooks** it should NOT inherit (`list_rulebooks` shows
+  which are always_on; default: inherit them all) →
+  `exclude_always_on_rulebooks=[...]`
+- which other rulebooks to **subscribe** → `subscribe_rulebooks=[...]`
+- which **design system** its UI is built from (`list_design_systems`; or
+  none) → `design_system_id=<id | -1>`
+- whether to **seed the standard starter Systems** so records can be tagged
+  from day one → `seed_systems=true|false`
+
+If `enter_project` returns an `inception` key, the project was never decided
+(it inherits its defaults silently): raise that ask once, with the defaults it
+carries, then `decide_project_inception(project_id, …)`. Existing projects
+were stamped "legacy" (inherit-all) and do not ask; any project can be
+re-decided. The rules/design-system/Systems tools still work one at a time —
+inception is the moment they are decided together, and the record of why.
+
 ## Where a new rule goes
 
 When codifying a rule, pick its home by **who it should bind** — and keep

src/scribe/mcp/auth.py

@@ -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).

src/scribe/mcp/server.py

@@ -37,24 +37,23 @@ in local files (CLAUDE.md, auto-memory); Scribe holds the single copy.
 
 Hierarchy: Project -> Milestone -> Task/Note. The map, by purpose:
 - ORIENT: enter_project(id) at session start — rules, open tasks, recent
-  notes, Systems and design system in one call.
+  notes, Systems, design system. `inception` key: ask what the project
+  inherits, decide_project_inception (create_project takes the same).
 - DO: create_task. Fixed a problem? kind="issue" (symptom -> root cause ->
   fix), never a work-log line on an unrelated task. Log with add_task_log;
   keep status honest — in_progress on start, done on finish.
 - PLAN work with an arc: start_planning. The plan IS a milestone; each step is
   a child task, not a checkbox. No local plan .md files.
-- CAPTURE: create_note. RECALL: search first, before answering about the
-  operator's work or opening a task — assume prior art exists, and pass the
+- CAPTURE: create_note. RECALL: search first — prior art exists; pass the
   active project_id to stay in scope.
 - WHERE work happens: Systems. Tag records with system_ids as you write;
   create_system when the area is unmodelled.
-- HOW to work: rules are pull-only and binding — call list_always_on_rules()
-  yourself at session start.
+- HOW: rules are binding — list_always_on_rules() at session start.
 - UI: the project's design system is binding — resolve_design_system /
   get_design_system_stylesheet before hand-writing a value.
 - REUSE: search snippets before writing a helper; record what you build with
   create_snippet; classify shapes against canon (classify_shapes) — a
-  consumer map is rows, never prose. Saved procedures are Processes (follow
+  consumer map is rows, never prose. Processes are saved procedures (follow
   verbatim). Deletes are trash-recoverable.
 
 A task is a note with status (*_note vs *_task tools).

src/scribe/mcp/tools/milestones.py

@@ -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),
     }
 
 

src/scribe/mcp/tools/notes.py

@@ -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
 
 

src/scribe/mcp/tools/projects.py

@@ -20,6 +20,7 @@ from scribe.mcp._context import current_user_id
 from scribe.mcp.tools import systems as systems_tools
 from scribe.services import coverage as coverage_svc
 from scribe.services import design_systems as design_systems_svc
+from scribe.services import inception as inception_svc
 from scribe.services import milestones as milestones_svc
 from scribe.services import notes as notes_svc
 from scribe.services import projects as projects_svc
@@ -80,6 +81,12 @@ async def enter_project(project_id: int) -> dict:
     create it with create_system rather than leaving the area unmodelled. Read
     a subsystem's accumulated records with list_system_records.
 
+    `inception` (milestone 297) appears ONLY when the project is yours and
+    nobody has decided what it inherits: it carries the current defaults
+    (which always-on rulebooks bind, design system, Systems), what to ask the
+    operator — once — and the decide_project_inception call that answers it;
+    it repeats on every enter until a decision is recorded.
+
     `systems_bootstrap` appears ONLY when the project has many records and no
     Systems at all — act on it before starting other work: create_system a
     starter vocabulary from the areas the project's records name, directly
@@ -141,6 +148,14 @@ async def enter_project(project_id: int) -> dict:
             uid, project_id
         )
 
+    # The inception ask (milestone 297): a project nobody has decided on
+    # inherits its defaults silently — always-on rulebooks, no design system,
+    # no Systems. Owner-only (deciding is the owner's), and only until a
+    # decision is recorded; the key is ABSENT otherwise (#2483).
+    inception_ask = None
+    if project.user_id == uid and not inception_svc.is_decided(project):
+        inception_ask = await inception_svc.inception_ask(uid, project_id)
+
     # Probably the largest surfacing by volume, and it emitted nothing — so
     # the pulls it caused floated unattributed and the surfaced:pulled ratio
     # ran against a denominator missing its biggest contributor (#2477). An
@@ -192,12 +207,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,
@@ -218,6 +228,8 @@ async def enter_project(project_id: int) -> dict:
     # readers to skip it (#2483), and this one exists to be acted on.
     if systems_bootstrap:
         out["systems_bootstrap"] = systems_bootstrap
+    if inception_ask:
+        out["inception"] = inception_ask
     return out
 
 
@@ -239,23 +251,47 @@ 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
 
 
+def _inception_choices(
+    exclude_always_on_rulebooks, subscribe_rulebooks, design_system_id, seed_systems,
+) -> dict | None:
+    """The tool args → an inception choices object, or None when no inception
+    arg was given at all (a bare create stays undecided and enter_project
+    asks). design_system_id: 0 = not stated, -1 = explicitly none, n = that
+    system."""
+    if (exclude_always_on_rulebooks is None and subscribe_rulebooks is None
+            and not design_system_id and seed_systems is None):
+        return None
+    return {
+        "exclude_always_on_rulebooks": list(exclude_always_on_rulebooks or []),
+        "subscribe_rulebooks": list(subscribe_rulebooks or []),
+        "design_system_id": None if design_system_id in (0, -1) else design_system_id,
+        "seed_systems": bool(seed_systems),
+    }
+
+
 async def create_project(
     title: str,
     description: str = "",
     goal: str = "",
     status: str = "active",
     color: str = "",
+    exclude_always_on_rulebooks: list[int] | None = None,
+    subscribe_rulebooks: list[int] | None = None,
+    design_system_id: int = 0,
+    seed_systems: bool | None = None,
 ) -> dict:
-    """Create a new project in Scribe.
+    """Create a new project in Scribe — and decide what it inherits.
+
+    A project's inheritance is a decision, not a default (milestone 297):
+    before calling, ask the operator the four inception questions and pass
+    the answers; a project created without any of them is UNDECIDED and
+    enter_project will ask until decide_project_inception records it.
+    Defaults if nobody decides: every always-on rulebook binds, nothing is
+    subscribed, no design system, no Systems.
 
     Args:
         title: Project name (required).
@@ -263,6 +299,14 @@ async def create_project(
         goal: The desired outcome or definition of done for the project.
         status: one of active (default), paused, completed, archived.
         color: Optional hex colour for the project card (e.g. "#6366f1").
+        exclude_always_on_rulebooks: always-on rulebook ids this project does
+            NOT inherit ([] = inherit them all). list_rulebooks shows which are
+            always_on.
+        subscribe_rulebooks: rulebook ids to subscribe (the non-always-on ones).
+        design_system_id: the design system this project's UI is built from
+            (list_design_systems); -1 = explicitly none; 0 = not stated.
+        seed_systems: true mints the standard starter Systems (CI & Release,
+            Auth & Access, …) so records can be tagged from day one.
     """
     uid = current_user_id()
     project = await projects_svc.create_project(
@@ -273,7 +317,52 @@ async def create_project(
         status=status,
         color=color or None,
     )
-    return project.to_dict()
+    data = project.to_dict()
+    choices = _inception_choices(
+        exclude_always_on_rulebooks, subscribe_rulebooks, design_system_id, seed_systems,
+    )
+    if choices is not None:
+        decided = await inception_svc.decide(uid, project.id, choices=choices, via="mcp")
+        data["inception"] = decided["inception"]
+        data["inception_effects"] = decided["effects"]
+    else:
+        data["inception_hint"] = (
+            "Undecided: this project inherits its defaults until "
+            "decide_project_inception records what it should inherit "
+            "(enter_project will ask)."
+        )
+    return data
+
+
+async def decide_project_inception(
+    project_id: int,
+    exclude_always_on_rulebooks: list[int] | None = None,
+    subscribe_rulebooks: list[int] | None = None,
+    design_system_id: int = 0,
+    seed_systems: bool | None = None,
+) -> dict:
+    """Record what a project inherits — answer enter_project's `inception` ask,
+    or re-decide later (milestone 297).
+
+    Owner-only. Applies the effects through the ordinary tools' paths —
+    exclude_always_on_rulebook, subscribe_project_to_rulebook,
+    set_project_design_system, the standard Systems seed — and writes the
+    decision on the project last, so get_project/enter_project can say why
+    the project has the rules, design and Systems it has. Re-deciding is
+    additive for exclusions/subscriptions (use include_always_on_rulebook /
+    unsubscribe_project_from_rulebook to undo one), replaces the design
+    system, and never re-seeds Systems a project already has.
+
+    Args: as create_project's inception args. Passing nothing records an
+    inherit-all decision (every always-on rulebook binds, no subscriptions,
+    no design system, no seed) — a valid answer, stated.
+    """
+    uid = current_user_id()
+    choices = _inception_choices(
+        exclude_always_on_rulebooks, subscribe_rulebooks, design_system_id, seed_systems,
+    ) or {}
+    decided = await inception_svc.decide(uid, project_id, choices=choices, via="mcp")
+    return {"project_id": project_id, **decided}
 
 
 async def update_project(
@@ -330,6 +419,6 @@ def register(mcp) -> None:
         get_project,
         create_project,
         update_project,
-        delete_project,
+        delete_project, decide_project_inception,
     ):
         mcp.tool(name=fn.__name__)(fn)

src/scribe/mcp/tools/repos.py

@@ -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}."
+        ),
     }
 
 

src/scribe/mcp/tools/rulebooks.py

@@ -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,38 +219,26 @@ 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:
+async def list_always_on_rules(project_id: int = 0) -> dict:
     """Return all rules from rulebooks flagged always_on for the current user.
 
     Call this at session start. Treat the returned rules as binding for the
     session — they apply regardless of which project (if any) is in scope.
     Pair with get_project(id).applicable_rules when working on a specific
     project to also load that project's subscription-derived rules.
+
+    Args:
+        project_id: 0 (default) = the user-wide set. Inside a project, pass
+            its id: an always-on rulebook the project EXCLUDED at inception
+            (see enter_project's `excluded_always_on`) is left out — the
+            project decided not to inherit it.
     """
     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),
-    }
+    rules = await rulebooks_svc.list_always_on_rules(uid, project_id=project_id)
+    return {"rules": [_rule_summary(r) for r in rules], "total": len(rules)}
 
 
 async def get_rule(rule_id: int) -> dict:
@@ -419,6 +413,35 @@ async def unsubscribe_project_from_rulebook(
 
 # ── Suppressions — project-level mute of rulebook rules / topics ────────
 
+async def exclude_always_on_rulebook(project_id: int, rulebook_id: int) -> dict:
+    """Opt a project OUT of a whole always-on rulebook (milestone 297).
+
+    Always-on rulebooks bind every project implicitly; an inception decision
+    can say "not this one, not here". The exclusion is total for that project
+    — list_always_on_rules(project_id), enter_project/get_project rules and
+    the session-start context all leave it out and name it under
+    `excluded_always_on`. Owner-only; the rulebook must be always_on (a
+    subscribed rulebook is left with unsubscribe_project_from_rulebook).
+    Idempotent; include_always_on_rulebook reverses it. Normally reached via
+    decide_project_inception, not by hand.
+    """
+    uid = current_user_id()
+    await rulebooks_svc.exclude_always_on_rulebook_for_project(
+        project_id=project_id, rulebook_id=rulebook_id, user_id=uid,
+    )
+    return {"project_id": project_id, "rulebook_id": rulebook_id, "excluded": True}
+
+
+async def include_always_on_rulebook(project_id: int, rulebook_id: int) -> dict:
+    """Reverse exclude_always_on_rulebook: the always-on rulebook binds this
+    project again. Idempotent."""
+    uid = current_user_id()
+    await rulebooks_svc.include_always_on_rulebook_for_project(
+        project_id=project_id, rulebook_id=rulebook_id, user_id=uid,
+    )
+    return {"project_id": project_id, "rulebook_id": rulebook_id, "excluded": False}
+
+
 async def suppress_rule_for_project(
     project_id: int, rule_id: int,
 ) -> dict:
@@ -482,5 +505,6 @@ def register(mcp) -> None:
         subscribe_project_to_rulebook, unsubscribe_project_from_rulebook,
         suppress_rule_for_project, unsuppress_rule_for_project,
         suppress_topic_for_project, unsuppress_topic_for_project,
+        exclude_always_on_rulebook, include_always_on_rulebook,
     ):
         mcp.tool(name=fn.__name__)(fn)

src/scribe/mcp/tools/shapes.py

@@ -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)

src/scribe/mcp/tools/snippets.py

@@ -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
 
 

src/scribe/mcp/tools/systems.py

@@ -30,10 +30,10 @@ _BOOTSTRAP_TITLES = 6
 # design (rule #115): archetypes any codebase could have, never one
 # install's subsystems. Mint freely beyond the list; the duplicate gate
 # guards sprawl.
-_STANDARD_SYSTEMS = (
-    "CI & Release", "Auth & Access", "Data Model & Storage", "API Surface",
-    "UI & Design", "Import & Export", "Background Jobs", "Observability",
-)
+# The standard vocabulary lives with the service (services/systems.
+# STANDARD_SYSTEMS) since milestone 297 — the inception seed mints it and this
+# ask names it, one list for both.
+_STANDARD_SYSTEMS = tuple(name for name, _charter in systems_svc.STANDARD_SYSTEMS)
 
 
 async def bootstrap_systems_ask(user_id: int, project_id: int) -> str | None:
@@ -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

src/scribe/mcp/tools/tasks.py

@@ -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

src/scribe/models/__init__.py

@@ -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

src/scribe/models/api_key.py

@@ -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),
         }

src/scribe/models/app_log.py

@@ -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),
         }

src/scribe/models/base.py

@@ -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."""

src/scribe/models/code_shape.py

@@ -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),
         }

src/scribe/models/design_system.py

@@ -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),
         }

src/scribe/models/forge_connection.py

@@ -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),
         }

src/scribe/models/group.py

@@ -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),
         }

src/scribe/models/invitation.py

@@ -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"),

src/scribe/models/milestone.py

@@ -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),
         }

src/scribe/models/note.py

@@ -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),
         }

src/scribe/models/note_draft.py

@@ -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),
         }

src/scribe/models/note_supersession.py

@@ -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),
         }

src/scribe/models/note_usage.py

@@ -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,

src/scribe/models/note_version.py

@@ -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

src/scribe/models/notification.py

@@ -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),
         }

src/scribe/models/password_reset.py

@@ -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"),

src/scribe/models/project.py

@@ -1,8 +1,9 @@
 import enum
 from sqlalchemy import BigInteger, ForeignKey, Integer, Text
+from sqlalchemy.dialects.postgresql import 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 ProjectStatus(str, enum.Enum):
@@ -36,6 +37,14 @@ class Project(Base, TimestampMixin, SoftDeleteMixin):
         BigInteger, ForeignKey("forge_connections.id", ondelete="SET NULL"),
         nullable=True,
     )
+    # The inception record (milestone 297): what this project was decided to
+    # inherit, when, and through which door — {decided_at, decided_by, via,
+    # choices: {exclude_always_on_rulebooks, subscribe_rulebooks,
+    # design_system_id, seed_systems}}. NULL means nobody has decided yet,
+    # and enter_project asks; the effects themselves live in the subscription
+    # / exclusion tables, design_system_id and the project's Systems — this is
+    # the WHY, kept so later surfaces can say it. See services/inception.py.
+    inception: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
 
     def to_dict(self) -> dict:
         return {
@@ -48,6 +57,7 @@ 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(),
+            "inception": self.inception,
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
         }

src/scribe/models/repo_binding.py

@@ -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),
         }

src/scribe/models/retrieval_log.py

@@ -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,

src/scribe/models/rulebook.py

@@ -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),
         }
 
 
@@ -153,6 +129,19 @@ project_rule_suppressions = Table(
     Column("created_at", DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)),
 )
 
+# A project's opt-out of a whole ALWAYS-ON rulebook (milestone 297): the
+# sibling of the two suppression tables below, one level up. Always-on
+# rulebooks bind every project implicitly; an inception decision can exclude
+# specific ones for this project, and get_applicable_rules /
+# list_always_on_rules(project_id) skip them. FKs CASCADE like the others.
+project_rulebook_exclusions = Table(
+    "project_rulebook_exclusions",
+    Base.metadata,
+    Column("project_id", BigInteger, ForeignKey("projects.id", ondelete="CASCADE"), primary_key=True),
+    Column("rulebook_id", BigInteger, ForeignKey("rulebooks.id", ondelete="CASCADE"), primary_key=True),
+    Column("created_at", DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)),
+)
+
 project_topic_suppressions = Table(
     "project_topic_suppressions",
     Base.metadata,

src/scribe/models/share.py

@@ -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),
         }

src/scribe/models/system.py

@@ -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),
         }
 
 

src/scribe/models/task_log.py

@@ -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),
         }

src/scribe/models/user.py

@@ -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,
         }

src/scribe/routes/admin.py

@@ -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(

src/scribe/routes/design_systems.py

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

src/scribe/routes/notes.py

@@ -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

src/scribe/routes/plugin.py

@@ -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"

src/scribe/routes/projects.py

@@ -5,6 +5,7 @@ from quart import Blueprint, g, jsonify, request
 
 from scribe.auth import login_required, get_current_user_id
 from scribe.routes.utils import not_found, parse_pagination
+from scribe.services import inception as inception_svc
 from scribe.services.milestones import list_milestones
 from scribe.services.notes import list_notes
 from scribe.services.projects import (
@@ -66,6 +67,15 @@ async def create_project_route():
     status = data.get("status", "active")
     if status not in ("active", "paused", "completed", "archived"):
         return jsonify({"error": "status must be 'active', 'paused', 'completed', or 'archived'"}), 400
+    # The inception decision rides the create (milestone 297): the UI's
+    # second step sends `inception: {choices}`; absent = undecided, and the
+    # project page shows the card until it is. Validated before the create
+    # so a bad decision never leaves a half-made project behind.
+    inception = data.get("inception")
+    if inception is not None:
+        error = inception_svc.validate_inception(inception)
+        if error:
+            return jsonify({"error": error}), 400
     project = await create_project(
         uid,
         title=data["title"],
@@ -74,7 +84,44 @@ async def create_project_route():
         color=data.get("color"),
         status=status,
     )
-    return jsonify(project.to_dict()), 201
+    out = project.to_dict()
+    if inception is not None:
+        try:
+            decided = await inception_svc.decide(uid, project.id, choices=inception, via="ui")
+        except ValueError as exc:
+            return jsonify({"error": str(exc), "project": out}), 400
+        out["inception"] = decided["inception"]
+        out["inception_effects"] = decided["effects"]
+    return jsonify(out), 201
+
+
+@projects_bp.route("/<int:project_id>/inception", methods=["POST"])
+@login_required
+async def decide_inception_route(project_id: int):
+    """Record (or re-record) what a project inherits — milestone 297.
+    Body: the choices object {exclude_always_on_rulebooks, subscribe_rulebooks,
+    design_system_id, seed_systems}; owner-only."""
+    uid = get_current_user_id()
+    data = await request.get_json() or {}
+    choices = data.get("choices", data)
+    try:
+        decided = await inception_svc.decide(uid, project_id, choices=choices, via="ui")
+    except ValueError as exc:
+        msg = str(exc)
+        status = 404 if "not found" in msg else 400
+        return jsonify({"error": msg}), status
+    return jsonify({"project_id": project_id, **decided})
+
+
+@projects_bp.route("/<int:project_id>/inception/defaults", methods=["GET"])
+@login_required
+async def inception_defaults_route(project_id: int):
+    """What the project inherits if nobody decides — the card's payload."""
+    uid = get_current_user_id()
+    try:
+        return jsonify(await inception_svc.current_defaults(uid, project_id))
+    except ValueError:
+        return not_found("Project")
 
 
 @projects_bp.route("/<int:project_id>", methods=["GET"])

src/scribe/routes/rulebooks.py

@@ -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,33 @@ 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
+    return "", 204
+
+
+@rulebooks_bp.post("/projects/<int:project_id>/exclusions/rulebooks/<int:rulebook_id>")
+@login_required
+async def exclude_project_rulebook(project_id: int, rulebook_id: int):
+    """Opt the project out of a whole always-on rulebook (milestone 297)."""
+    try:
+        await rulebooks_svc.exclude_always_on_rulebook_for_project(
+            project_id=project_id, rulebook_id=rulebook_id, user_id=get_current_user_id(),
+        )
+    except ValueError as exc:
+        msg = str(exc)
+        return jsonify({"error": msg}), (400 if "not always-on" in msg else 404)
+    return "", 204
+
+
+@rulebooks_bp.delete("/projects/<int:project_id>/exclusions/rulebooks/<int:rulebook_id>")
+@login_required
+async def include_project_rulebook(project_id: int, rulebook_id: int):
+    try:
+        await rulebooks_svc.include_always_on_rulebook_for_project(
+            project_id=project_id, rulebook_id=rulebook_id, user_id=get_current_user_id(),
         )
     except ValueError as exc:
         return jsonify({"error": str(exc)}), 404
@@ -303,7 +326,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", ""),

src/scribe/routes/settings.py

@@ -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(

src/scribe/routes/trash.py

@@ -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})

src/scribe/services/api_keys.py

@@ -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(

src/scribe/services/auth.py

@@ -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
+        )

src/scribe/services/background.py

@@ -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:

src/scribe/services/backup.py

@@ -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 (
@@ -19,6 +19,7 @@ from scribe.models.rulebook import (
     Rulebook,
     RulebookTopic,
     project_rule_suppressions,
+    project_rulebook_exclusions,
     project_rulebook_subscriptions,
     project_topic_suppressions,
 )
@@ -42,8 +43,13 @@ 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.
+# v10 (2026-08) added projects.inception + project_rulebook_exclusions
+# (milestone 297): the WHY a project inherits what it does, and its opt-outs.
 # Bump when the serialized schema changes.
-BACKUP_VERSION = 8
+BACKUP_VERSION = 10
 
 # Every table this backup carries, by its REAL name. Paired with _NOT_INCLUDED
 # below, these two lists must together account for the entire schema — which is
@@ -57,12 +63,12 @@ _BACKED_UP = [
     "users", "projects", "milestones", "notes", "task_logs", "note_drafts",
     "note_versions", "settings", "rulebooks", "rulebook_topics", "rules",
     "project_rulebook_subscriptions", "project_rule_suppressions",
-    "project_topic_suppressions",
+    "project_topic_suppressions", "project_rulebook_exclusions",
     # v5 (2026-08): the five-year gap this list was written to stop.
     "systems", "record_systems", "design_systems", "design_tokens",
     "note_usage_events", "repo_bindings", "note_supersessions",
     # 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
@@ -109,6 +115,10 @@ def _topic_suppression_rows(rows) -> list[dict]:
     return [{"project_id": r.project_id, "topic_id": r.topic_id} for r in rows]
 
 
+def _rulebook_exclusion_rows(rows) -> list[dict]:
+    return [{"project_id": r.project_id, "rulebook_id": r.rulebook_id} for r in rows]
+
+
 # The v5 sections. Pure row-builders like the join-table helpers above, for the
 # same reason: CI has no database, so a serialiser that is a plain function is
 # one that can actually be tested.
@@ -182,6 +192,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 +203,144 @@ 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,
+            "design_system_id": p.design_system_id,
+            "inception": p.inception,
+            "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 +377,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()
@@ -237,6 +392,9 @@ async def export_full_backup() -> dict:
         topic_suppressions = (await session.execute(
             select(project_topic_suppressions)
         )).all()
+        rulebook_exclusions = (await session.execute(
+            select(project_rulebook_exclusions)
+        )).all()
 
     return {
         "version": BACKUP_VERSION,
@@ -247,151 +405,21 @@ 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),
+        "rulebook_exclusions": _rulebook_exclusion_rows(rulebook_exclusions),
         "systems": _system_rows(systems),
         "record_systems": _record_system_rows(record_systems),
         "design_systems": _design_system_rows(design_systems),
@@ -401,6 +429,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 +506,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()
@@ -511,8 +545,13 @@ async def export_user_backup(user_id: int) -> dict:
                     project_topic_suppressions.c.project_id.in_(project_ids)
                 )
             )).all()
+            rulebook_exclusions = (await session.execute(
+                select(project_rulebook_exclusions).where(
+                    project_rulebook_exclusions.c.project_id.in_(project_ids)
+                )
+            )).all()
         else:
-            subscriptions = rule_suppressions = topic_suppressions = []
+            subscriptions = rule_suppressions = topic_suppressions = rulebook_exclusions = []
 
     return {
         "version": BACKUP_VERSION,
@@ -526,138 +565,20 @@ 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),
+        "rulebook_exclusions": _rulebook_exclusion_rows(rulebook_exclusions),
         "systems": _system_rows(systems),
         "record_systems": _record_system_rows(record_systems),
         "design_systems": _design_system_rows(design_systems),
@@ -667,6 +588,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),
     }
 
 
@@ -767,10 +689,11 @@ async def _restore_v2(data: dict) -> dict:
         "task_logs": 0, "note_drafts": 0, "note_versions": 0,
         "settings": 0, "rulebooks": 0, "rulebook_topics": 0, "rules": 0,
         "rulebook_subscriptions": 0, "rule_suppressions": 0,
-        "topic_suppressions": 0,
+        "topic_suppressions": 0, "rulebook_exclusions": 0,
         "systems": 0, "record_systems": 0, "design_systems": 0,
         "design_tokens": 0, "note_usage_events": 0, "repo_bindings": 0,
         "note_supersessions": 0, "code_shapes": 0, "code_shape_events": 0,
+        "code_shape_uses": 0,
     }
 
     async with async_session() as session:
@@ -1029,6 +952,17 @@ async def _restore_v2(data: dict) -> dict:
             ))
             stats["topic_suppressions"] += 1
 
+        # 14b. Always-on rulebook exclusions (v10, milestone 297)
+        for exc in data.get("rulebook_exclusions", []):
+            mapped_pid = project_id_map.get(exc.get("project_id", 0))
+            mapped_rbid = rulebook_id_map.get(exc.get("rulebook_id", 0))
+            if mapped_pid is None or mapped_rbid is None:
+                continue
+            await session.execute(project_rulebook_exclusions.insert().values(
+                project_id=mapped_pid, rulebook_id=mapped_rbid,
+            ))
+            stats["rulebook_exclusions"] += 1
+
         # --- v5 sections. Every one is data.get()-guarded, so a v2/v3/v4
         # payload restores without them rather than failing on an absent key.
 
@@ -1219,6 +1153,49 @@ 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
+
+        # v10: a project's design-system pointer and its inception record ride
+        # the project but point at design systems and rulebooks restored AFTER
+        # it — so they are written last, with ids re-mapped. An id that did
+        # not survive drops out of the record rather than dangling.
+        for p_data in data.get("projects", []):
+            new_pid = project_id_map.get(p_data.get("id") or 0)
+            if new_pid is None:
+                continue
+            proj = await session.get(Project, new_pid)
+            if proj is None:
+                continue
+            old_ds = p_data.get("design_system_id")
+            if old_ds:
+                proj.design_system_id = design_system_id_map.get(old_ds)
+            inception = p_data.get("inception")
+            if isinstance(inception, dict):
+                choices = dict(inception.get("choices") or {})
+                choices["exclude_always_on_rulebooks"] = [
+                    rulebook_id_map[i] for i in choices.get("exclude_always_on_rulebooks") or []
+                    if i in rulebook_id_map
+                ]
+                choices["subscribe_rulebooks"] = [
+                    rulebook_id_map[i] for i in choices.get("subscribe_rulebooks") or []
+                    if i in rulebook_id_map
+                ]
+                ds = choices.get("design_system_id")
+                choices["design_system_id"] = design_system_id_map.get(ds) if ds else None
+                proj.inception = {**inception, "choices": choices}
+
         await session.commit()
 
     logger.info("Restored v2/v3 backup: %s", stats)

src/scribe/services/coverage.py

@@ -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,68 @@ 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.
+        if kind == "css":
+            # One-line rules (`.x { color: red; }`) carry their declarations on
+            # the selector line itself; a block that is only the selector plus
+            # trailing blanks must not hash to the empty string (which grouped
+            # 68 unrelated one-liners as one "copy" on first deploy, #2872).
+            first = lines[i]
+            brace = first.find("{")
+            head = [first[brace + 1:]] if brace >= 0 and first[brace + 1:].strip() else []
+            hashed = head + block[1:]
+            if not any(x.strip() for x in hashed):
+                hashed = block
+        else:
+            hashed = 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 +276,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 +307,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 +419,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 +479,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 +500,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 +637,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 +658,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 []]

src/scribe/services/dashboard.py

@@ -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:

src/scribe/services/db_maintenance.py

@@ -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
     ]

src/scribe/services/db_maintenance_scheduler.py

@@ -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()

src/scribe/services/dedup.py

@@ -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:

src/scribe/services/inception.py

@@ -0,0 +1,272 @@
+"""Project inception — what a project was decided to inherit (milestone 297).
+
+A project's inheritance is a decision, not a default. The record lives on
+``projects.inception``::
+
+    {
+      "decided_at": "<iso>", "decided_by": <user id> | null,
+      "via": "mcp" | "ui" | "legacy",
+      "choices": {
+        "exclude_always_on_rulebooks": [rulebook ids],
+        "subscribe_rulebooks": [rulebook ids],
+        "design_system_id": <id> | null,
+        "seed_systems": bool
+      }
+    }
+
+NULL = undecided → enter_project asks. ``legacy`` is the migration's stamp on
+projects that existed before the step did (inherit-all / no design system /
+no seed), so the ask fires only for projects created after this shipped.
+
+The shape and its validator are pure; ``decide`` composes the existing
+services — always-on exclusions, subscriptions, set_project_design_system,
+the standard Systems seed — checks every target BEFORE touching anything,
+applies the effects (each idempotent), and writes the record LAST, so a
+half-applied decision is re-runnable rather than recorded as done.
+``current_defaults`` is what the enter_project ask shows: what binds today
+if nobody decides.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import select
+
+from scribe.models import async_session
+from scribe.models.project import Project
+from scribe.models.rulebook import Rulebook
+
+INCEPTION_VIAS = ("mcp", "ui", "legacy")
+CHOICE_KEYS = ("exclude_always_on_rulebooks", "subscribe_rulebooks", "design_system_id", "seed_systems")
+
+
+def _is_id_list(value) -> bool:
+    return isinstance(value, list) and all(
+        isinstance(v, int) and not isinstance(v, bool) and v > 0 for v in value
+    )
+
+
+def validate_inception(choices) -> str | None:
+    """The structural error an inception ``choices`` object would earn, or
+    None. Pure and checked BEFORE any effect is applied: a decision either
+    applies whole or errors whole (the StrictArgs lesson, #2709).
+
+    Accepts the four keys, each optional: two id lists (positive ints, no
+    duplicates between exclude and subscribe), ``design_system_id`` an int
+    or None, ``seed_systems`` a bool. Unknown keys are an error — a typo
+    must not become a silently ignored choice."""
+    if not isinstance(choices, dict):
+        return "choices must be an object"
+    unknown = sorted(set(choices) - set(CHOICE_KEYS))
+    if unknown:
+        return f"unknown inception choice(s): {', '.join(unknown)} (one of: {', '.join(CHOICE_KEYS)})"
+    excl = choices.get("exclude_always_on_rulebooks") or []
+    subs = choices.get("subscribe_rulebooks") or []
+    if not _is_id_list(excl):
+        return "exclude_always_on_rulebooks must be a list of rulebook ids"
+    if not _is_id_list(subs):
+        return "subscribe_rulebooks must be a list of rulebook ids"
+    both = sorted(set(excl) & set(subs))
+    if both:
+        return f"rulebook(s) {both} cannot be both excluded and subscribed"
+    ds = choices.get("design_system_id")
+    if ds is not None and (isinstance(ds, bool) or not isinstance(ds, int) or ds <= 0):
+        return "design_system_id must be a positive id or null"
+    seed = choices.get("seed_systems", False)
+    if not isinstance(seed, bool):
+        return "seed_systems must be true or false"
+    return None
+
+
+def normalize_choices(choices: dict | None) -> dict:
+    """The four keys, always present, in canonical form — what gets stored
+    and what the UI/agent reads back. Call after validate_inception."""
+    choices = choices or {}
+    return {
+        "exclude_always_on_rulebooks": sorted(set(choices.get("exclude_always_on_rulebooks") or [])),
+        "subscribe_rulebooks": sorted(set(choices.get("subscribe_rulebooks") or [])),
+        "design_system_id": choices.get("design_system_id"),
+        "seed_systems": bool(choices.get("seed_systems", False)),
+    }
+
+
+def is_decided(project) -> bool:
+    """A project is decided once its inception record exists (any via)."""
+    return bool(getattr(project, "inception", None))
+
+
+async def current_defaults(user_id: int, project_id: int) -> dict:
+    """What the project inherits if nobody decides — the ask's payload.
+
+    {always_on_rulebooks: [{id,title}], other_rulebooks: [{id,title}],
+     excluded_always_on: [...], subscribed_rulebooks: [...],
+     design_system_id, design_systems: [{id,title}], systems: <count>}.
+    Instance-agnostic: an install with no rulebooks / design systems shows
+    empty lists, and the ask says so rather than inventing a default.
+    """
+    from scribe.services import design_systems as design_systems_svc
+    from scribe.services import projects as projects_svc
+    from scribe.services import rulebooks as rulebooks_svc
+    from scribe.services import systems as systems_svc
+
+    project = await projects_svc.get_project(user_id, project_id)
+    if project is None:
+        raise ValueError(f"project {project_id} not found")
+    async with async_session() as session:
+        rows = (
+            await session.execute(
+                select(Rulebook.id, Rulebook.title, Rulebook.always_on)
+                .where(Rulebook.owner_user_id == user_id, Rulebook.deleted_at.is_(None))
+                .order_by(Rulebook.title)
+            )
+        ).all()
+    applicable = await rulebooks_svc.get_applicable_rules(project_id, user_id, limit=1)
+    designs = await design_systems_svc.list_design_systems(user_id)
+    systems = await systems_svc.list_systems(user_id, project_id, include_archived=True)
+    return {
+        "always_on_rulebooks": [{"id": i, "title": t} for i, t, on in rows if on],
+        "other_rulebooks": [{"id": i, "title": t} for i, t, on in rows if not on],
+        "excluded_always_on": applicable.get("excluded_always_on", []),
+        "subscribed_rulebooks": applicable.get("subscribed_rulebooks", []),
+        "design_system_id": project.design_system_id,
+        "design_systems": [{"id": d.id, "title": d.title} for d in designs],
+        "systems": len(systems),
+    }
+
+
+async def _check_targets(user_id: int, choices: dict) -> None:
+    """Every id a decision names must be the caller's (or readable) BEFORE any
+    effect lands — a decision applies whole or errors whole."""
+    from scribe.services import access
+
+    wanted = set(choices["exclude_always_on_rulebooks"]) | set(choices["subscribe_rulebooks"])
+    if wanted:
+        async with async_session() as session:
+            rows = (
+                await session.execute(
+                    select(Rulebook.id, Rulebook.always_on).where(
+                        Rulebook.id.in_(wanted),
+                        Rulebook.owner_user_id == user_id,
+                        Rulebook.deleted_at.is_(None),
+                    )
+                )
+            ).all()
+        found = {rid: on for rid, on in rows}
+        missing = sorted(wanted - set(found))
+        if missing:
+            raise ValueError(f"rulebook(s) {missing} not found (or not yours)")
+        not_always = sorted(r for r in choices["exclude_always_on_rulebooks"] if not found[r])
+        if not_always:
+            raise ValueError(
+                f"rulebook(s) {not_always} are not always-on — only always-on rulebooks "
+                "can be excluded; a subscribed rulebook is simply not subscribed"
+            )
+    ds = choices["design_system_id"]
+    if ds is not None and not await access.can_read_design_system(user_id, ds):
+        raise ValueError(f"design system {ds} not found (or not readable)")
+
+
+async def decide(
+    user_id: int,
+    project_id: int,
+    *,
+    choices: dict | None,
+    via: str,
+) -> dict:
+    """Record a project's inception decision and apply it (milestone 297).
+
+    Owner-only. Validates the choices (pure) and every target (owned /
+    readable) first; then, each idempotent: exclude the named always-on
+    rulebooks, subscribe the named rulebooks, point the project at the design
+    system (None = explicitly none), seed the standard Systems if asked and
+    the project has none; then write ``projects.inception`` LAST. Re-deciding
+    is additive for exclusions/subscriptions (nothing is silently dropped —
+    include/unsubscribe are explicit calls), replaces the design system, and
+    re-seeds nothing a project already has.
+
+    Returns {"inception": <record>, "effects": {excluded, subscribed,
+    design_system_id, systems_seeded}}.
+    """
+    from scribe.services import design_systems as design_systems_svc
+    from scribe.services import projects as projects_svc
+    from scribe.services import rulebooks as rulebooks_svc
+    from scribe.services import systems as systems_svc
+
+    if via not in INCEPTION_VIAS or via == "legacy":
+        raise ValueError("via must be 'mcp' or 'ui' ('legacy' is the migration's stamp)")
+    error = validate_inception(choices or {})
+    if error:
+        raise ValueError(error)
+    choices = normalize_choices(choices)
+    project = await projects_svc.get_project(user_id, project_id)   # owner-scoped
+    if project is None:
+        raise ValueError(f"project {project_id} not found (or not yours)")
+    await _check_targets(user_id, choices)
+
+    for rb in choices["exclude_always_on_rulebooks"]:
+        await rulebooks_svc.exclude_always_on_rulebook_for_project(project_id, rb, user_id)
+    for rb in choices["subscribe_rulebooks"]:
+        await rulebooks_svc.subscribe_project(project_id, rb, user_id)
+    if not await design_systems_svc.set_project_design_system(
+        user_id, project_id, choices["design_system_id"]
+    ):
+        raise ValueError("could not set the design system (no write on the project?)")
+    seeded = (
+        await systems_svc.seed_standard_systems(user_id, project_id)
+        if choices["seed_systems"] else []
+    )
+
+    record = {
+        "decided_at": datetime.now(timezone.utc).isoformat(),
+        "decided_by": user_id,
+        "via": via,
+        "choices": choices,
+    }
+    async with async_session() as session:
+        row = await session.get(Project, project_id)
+        row.inception = record
+        row.updated_at = datetime.now(timezone.utc)
+        await session.commit()
+    return {
+        "inception": record,
+        "effects": {
+            "excluded": choices["exclude_always_on_rulebooks"],
+            "subscribed": choices["subscribe_rulebooks"],
+            "design_system_id": choices["design_system_id"],
+            "systems_seeded": [sy.name for sy in seeded],
+        },
+    }
+
+
+async def inception_ask(user_id: int, project_id: int) -> dict:
+    """The enter_project ask for an undecided project (milestone 297) — the
+    sibling of the systems-bootstrap ask (#2683): the project's OWN current
+    defaults, what to ask the operator, and the exact call that answers it.
+    Fail-open: a hint must never break the call it rides on."""
+    try:
+        defaults = await current_defaults(user_id, project_id)
+    except Exception:
+        return {}
+    always = ", ".join(f"{r['title']} (#{r['id']})" for r in defaults["always_on_rulebooks"]) or "none"
+    others = ", ".join(f"{r['title']} (#{r['id']})" for r in defaults["other_rulebooks"]) or "none"
+    designs = ", ".join(f"{d['title']} (#{d['id']})" for d in defaults["design_systems"]) or "none"
+    return {
+        "defaults": defaults,
+        "ask": (
+            "This project has no inception decision: nobody has said what it "
+            f"inherits. Today, by default: always-on rulebooks binding it — {always}; "
+            f"rulebooks it could subscribe to — {others}; design system — "
+            f"{'#' + str(defaults['design_system_id']) if defaults['design_system_id'] else 'none'} "
+            f"(available: {designs}); Systems — {defaults['systems']}. Ask the operator, "
+            "once: which always-on rulebooks to EXCLUDE here (default: none), which "
+            "rulebooks to subscribe, which design system (or none), and whether to seed "
+            "the standard starter Systems — then record the answers. This ask repeats on "
+            "every enter_project until a decision is recorded."
+        ),
+        "call": (
+            f"decide_project_inception(project_id={project_id}, "
+            "exclude_always_on_rulebooks=[...], subscribe_rulebooks=[...], "
+            "design_system_id=<id | -1 for none>, seed_systems=<true|false>)"
+        ),
+    }
+

src/scribe/services/knowledge.py

@@ -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
 

src/scribe/services/logging.py

@@ -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

src/scribe/services/milestones.py

@@ -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, [])

src/scribe/services/note_usage.py

@@ -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

src/scribe/services/notifications.py

@@ -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()

src/scribe/services/planning.py

@@ -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,
     }

src/scribe/services/plugin_context.py

@@ -1097,7 +1097,14 @@ async def build_session_context(
     at _MAX_CHARS with an explicit truncation note so the hook can pass it
     through verbatim.
     """
-    rules = await rulebooks_svc.list_always_on_rules(user_id)
+    # Inside a project, the always-on set is the project's: an inception
+    # exclusion (milestone 297) takes a rulebook out of this block, and is
+    # named below so the departure is visible rather than silent.
+    rules = await rulebooks_svc.list_always_on_rules(user_id, project_id=project_id)
+    excluded = (
+        await rulebooks_svc.excluded_always_on_rulebooks(user_id, project_id)
+        if project_id else []
+    )
     topic_map = await _topic_titles({r.topic_id for r in rules if r.topic_id})
 
     lines: list[str] = [
@@ -1119,6 +1126,12 @@ async def build_session_context(
             heading = topic_map.get(r.topic_id, "ungrouped") if r.topic_id else "ungrouped"
             lines.append(f"### {heading}")
         lines.append(f"- [{r.id}] {r.title}")
+    if excluded:
+        names = ", ".join(f"{e['title']} (#{e['id']})" for e in excluded)
+        lines += [
+            "",
+            f"Excluded for this project by its inception decision (not binding here): {names}.",
+        ]
 
     project_dict: dict | None = None
     if project_id:

src/scribe/services/projects.py

@@ -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:

src/scribe/services/recurrence_scheduler.py

@@ -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()

src/scribe/services/repo_bindings.py

@@ -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).
 

src/scribe/services/rulebooks.py

@@ -394,15 +394,57 @@ async def list_rules(
         return rulebook_rules + list(proj_result.scalars().all())
 
 
-async def list_always_on_rules(user_id: int, limit: int = 100) -> list[Rule]:
+def _excluded_rulebook_ids_q(project_id: int):
+    """Subquery: the always-on rulebooks this project opted out of at
+    inception (milestone 297) — used by every rule-resolution path so an
+    exclusion is total, not just cosmetic."""
+    from scribe.models.rulebook import project_rulebook_exclusions
+
+    return select(project_rulebook_exclusions.c.rulebook_id).where(
+        project_rulebook_exclusions.c.project_id == project_id
+    )
+
+
+async def excluded_always_on_rulebooks(user_id: int, project_id: int) -> list[dict]:
+    """[{id, title}] of the always-on rulebooks excluded for ``project_id``
+    (owner-scoped). Empty for an undecided or inherit-all project."""
+    from scribe.models.rulebook import project_rulebook_exclusions
+
+    if not project_id:
+        return []
+    async with async_session() as session:
+        rows = (
+            await session.execute(
+                select(Rulebook.id, Rulebook.title)
+                .join(project_rulebook_exclusions,
+                      project_rulebook_exclusions.c.rulebook_id == Rulebook.id)
+                .where(
+                    project_rulebook_exclusions.c.project_id == project_id,
+                    Rulebook.owner_user_id == user_id,
+                    Rulebook.deleted_at.is_(None),
+                )
+                .order_by(Rulebook.title)
+            )
+        ).all()
+    return [{"id": rid, "title": title} for rid, title in rows]
+
+
+async def list_always_on_rules(
+    user_id: int, limit: int = 100, project_id: int = 0,
+) -> list[Rule]:
     """Return all rules from rulebooks flagged always_on for the user.
 
     Called by the MCP tool of the same name at session start to load the
     standing rules that apply regardless of which project (if any) is in
     scope. Ordering matches list_rules so results are stable across calls.
+
+    ``project_id`` (milestone 297): inside a project that excluded specific
+    always-on rulebooks at inception, those rulebooks' rules are NOT
+    returned — the project decided not to inherit them. 0 = the user-wide
+    set, which is what a session sees before a project is in scope.
     """
     async with async_session() as session:
-        result = await session.execute(
+        q = (
             select(Rule)
             .join(RulebookTopic, Rule.topic_id == RulebookTopic.id)
             .join(Rulebook, RulebookTopic.rulebook_id == Rulebook.id)
@@ -413,10 +455,13 @@ async def list_always_on_rules(user_id: int, limit: int = 100) -> list[Rule]:
                 RulebookTopic.deleted_at.is_(None),
                 Rulebook.deleted_at.is_(None),
             )
-            .order_by(
+        )
+        if project_id:
+            q = q.where(Rulebook.id.notin_(_excluded_rulebook_ids_q(project_id)))
+        result = await session.execute(
+            q.order_by(
                 Rulebook.id, RulebookTopic.order_index, Rule.order_index, Rule.title,
-            )
-            .limit(limit)
+            ).limit(limit)
         )
         return list(result.scalars().all())
 
@@ -489,6 +534,7 @@ async def delete_rule(rule_id: int, user_id: int) -> None:
 # ── Subscriptions + get_applicable_rules ───────────────────────────────
 
 from sqlalchemy import insert, delete as sql_delete
+from sqlalchemy.exc import IntegrityError
 
 
 async def subscribe_project(
@@ -568,6 +614,51 @@ async def unsuppress_rule_for_project(
         await session.commit()
 
 
+async def exclude_always_on_rulebook_for_project(
+    project_id: int, rulebook_id: int, user_id: int,
+) -> None:
+    """Opt one project out of a whole ALWAYS-ON rulebook (milestone 297).
+    Owner-only on both sides; the rulebook must be always_on — a subscribed
+    rulebook is left by unsubscribing, not excluding. Idempotent."""
+    from scribe.models.rulebook import project_rulebook_exclusions
+
+    async with async_session() as session:
+        await _assert_project_owned(session, project_id, user_id)
+        await _assert_rulebook_owned(session, rulebook_id, user_id)
+        rb = await session.get(Rulebook, rulebook_id)
+        if rb is None or not rb.always_on:
+            raise ValueError(
+                f"rulebook {rulebook_id} is not always-on — it binds only by "
+                "subscription; unsubscribe_project_from_rulebook instead"
+            )
+        try:
+            await session.execute(
+                insert(project_rulebook_exclusions).values(
+                    project_id=project_id, rulebook_id=rulebook_id,
+                )
+            )
+            await session.commit()
+        except IntegrityError:
+            await session.rollback()  # already excluded — idempotent
+
+
+async def include_always_on_rulebook_for_project(
+    project_id: int, rulebook_id: int, user_id: int,
+) -> None:
+    """Undo exclude_always_on_rulebook_for_project. Idempotent."""
+    from scribe.models.rulebook import project_rulebook_exclusions
+
+    async with async_session() as session:
+        await _assert_project_owned(session, project_id, user_id)
+        await session.execute(
+            sql_delete(project_rulebook_exclusions).where(
+                project_rulebook_exclusions.c.project_id == project_id,
+                project_rulebook_exclusions.c.rulebook_id == rulebook_id,
+            )
+        )
+        await session.commit()
+
+
 async def suppress_topic_for_project(
     project_id: int, topic_id: int, user_id: int,
 ) -> None:
@@ -731,6 +822,9 @@ async def get_applicable_rules(
                 Rule.deleted_at.is_(None),
                 RulebookTopic.deleted_at.is_(None),
                 Rulebook.deleted_at.is_(None),
+                # An inception exclusion is total (milestone 297): a rulebook the
+                # project opted out of contributes nothing, subscribed or not.
+                Rulebook.id.notin_(_excluded_rulebook_ids_q(project_id)),
             )
             .order_by(
                 Rulebook.id, RulebookTopic.order_index, Rule.order_index, Rule.title,
@@ -778,4 +872,28 @@ async def get_applicable_rules(
         "suppressed_topics": suppressed_topics,
         "truncated": truncated,
         "subscribed_rulebooks": subscribed_rulebooks,
+        "excluded_always_on": await excluded_always_on_rulebooks(user_id, project_id),
+    }
+
+
+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 seven 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.
+    `excluded_always_on` (milestone 297) names the always-on rulebooks this
+    project decided NOT to inherit, so the departure is visible wherever the
+    rules are.
+    """
+    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", []),
+        "excluded_always_on": applicable.get("excluded_always_on", []),
     }