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

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;

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/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/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
@@ -213,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
 
 
@@ -238,14 +255,43 @@ async def get_project(project_id: int) -> dict:
     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).
@@ -253,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(
@@ -263,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(
@@ -320,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

@@ -222,16 +222,22 @@ async def list_rules(
     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)
+    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)}
 
 
@@ -407,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:
@@ -470,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:

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/code_shape.py

@@ -1,4 +1,4 @@
-from datetime import datetime
+from datetime import datetime, timezone
 
 from sqlalchemy import (
     BigInteger,
@@ -16,10 +16,30 @@ from scribe.models import Base
 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,6 +173,7 @@ 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": iso(self.classified_at),
             "first_seen_commit": self.first_seen_commit,
@@ -167,6 +189,81 @@ class CodeShape(Base, TimestampMixin):
             "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),
+        }
+
 
 # What a shape's history records (#2793). Not "appeared" — first_seen and
 # created_at already say that on the row; history is for what CHANGED:

src/scribe/models/project.py

@@ -1,5 +1,6 @@
 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 SoftDeleteMixin, TimestampMixin, iso
@@ -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,
+            "inception": self.inception,
             "created_at": iso(self.created_at),
             "updated_at": iso(self.updated_at),
         }

src/scribe/models/repo_binding.py

@@ -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,
+            "ref": self.ref,
             "created_at": iso(self.created_at),
             "updated_at": iso(self.updated_at),
         }

src/scribe/models/rulebook.py

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

@@ -288,6 +288,32 @@ async def unsuppress_project_topic(project_id: int, topic_id: int):
     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
+    return "", 204
+
+
 @rulebooks_bp.post("/projects/<int:project_id>/rules")
 @login_required
 async def create_project_rule(project_id: int):

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}
@@ -212,6 +226,8 @@ def _project_rows(rows) -> list[dict]:
             "id": p.id, "user_id": p.user_id, "title": p.title,
             "description": p.description, "goal": p.goal, "status": p.status,
             "color": p.color,
+            "design_system_id": p.design_system_id,
+            "inception": p.inception,
             "created_at": p.created_at.isoformat(),
             "updated_at": p.updated_at.isoformat(),
         }
@@ -361,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()
@@ -373,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,
@@ -397,6 +419,7 @@ async def export_full_backup() -> dict:
         "rulebook_subscriptions": _subscription_rows(subscriptions),
         "rule_suppressions": _rule_suppression_rows(rule_suppressions),
         "topic_suppressions": _topic_suppression_rows(topic_suppressions),
+        "rulebook_exclusions": _rulebook_exclusion_rows(rulebook_exclusions),
         "systems": _system_rows(systems),
         "record_systems": _record_system_rows(record_systems),
         "design_systems": _design_system_rows(design_systems),
@@ -406,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),
     }
 
 
@@ -482,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()
@@ -516,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,
@@ -544,6 +578,7 @@ async def export_user_backup(user_id: int) -> dict:
         "rulebook_subscriptions": _subscription_rows(subscriptions),
         "rule_suppressions": _rule_suppression_rows(rule_suppressions),
         "topic_suppressions": _topic_suppression_rows(topic_suppressions),
+        "rulebook_exclusions": _rulebook_exclusion_rows(rulebook_exclusions),
         "systems": _system_rows(systems),
         "record_systems": _record_system_rows(record_systems),
         "design_systems": _design_system_rows(design_systems),
@@ -553,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),
     }
 
 
@@ -653,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:
@@ -915,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.
 
@@ -1105,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/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,6 +16,7 @@ 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
@@ -76,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()
         ):
@@ -99,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)})"

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/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,6 +872,7 @@ 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),
     }
 
 
@@ -786,9 +881,12 @@ def rules_payload(applicable: dict) -> dict:
 
     Every surface that hands rules to an agent (enter_project, get_project,
     get_milestone, get_task for legacy plans, start_planning) carries the
-    same six keys under the same names — so a reader learns them once. One
+    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"],
@@ -797,4 +895,5 @@ def rules_payload(applicable: dict) -> dict:
         "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", []),
     }

src/scribe/services/shape_ledger.py

@@ -30,7 +30,7 @@ from typing import Iterable, NamedTuple
 from sqlalchemy import select
 
 from scribe.models import async_session
-from scribe.models.code_shape import CodeShape, CodeShapeEvent
+from scribe.models.code_shape import REASON_CODES, CodeShape, CodeShapeEvent, CodeShapeUse
 from scribe.models.base import iso
 
 logger = logging.getLogger(__name__)
@@ -65,6 +65,17 @@ def location_covers(loc_path: str, loc_symbol: str, path: str, name: str) -> boo
     return _path_touches(loc_path, path)
 
 
+# The rows the machine may still speak about: nobody's judgment stands on
+# them. `scoped` (#2869) is the sync's own by-construction stamp — the
+# proposer, derive grouping, divergence, hook evidence and sweeps treat it
+# like the todo; only the human todo (`unclassified`) excludes it.
+_MECHANICAL_TODO = ("unclassified", "scoped")
+_SCOPED_REASON = (
+    "by construction: a Vue component's scoped <style> rule / <script setup> "
+    "function — unreachable from any other file (stamped by the coverage sync)"
+)
+
+
 async def sync_repo_shapes(
     project_id: int,
     repo_key: str,
@@ -76,7 +87,9 @@ async def sync_repo_shapes(
 
     ``shapes`` are (path, kind, name) triples, or the richer ArchiveShape
     records (#2792) whose 4th/5th fields — signature, body_sha — refresh the
-    row's content fingerprint. ``seen_marker`` is the commit the archive was
+    row's content fingerprint, and whose 7th (#2869) says the shape is a
+    one-off by construction: such rows are stamped `scoped` (mechanical)
+    while unjudged, and un-stamped if a later tree makes them reachable. ``seen_marker`` is the commit the archive was
     read at when the forge can say, else the ref name — provenance sugar;
     the row timestamps carry the when.
     """
@@ -96,20 +109,32 @@ async def sync_repo_shapes(
             path, kind, name = shape[0], shape[1], shape[2]
             signature = shape[3] if len(shape) > 3 else ""
             body_sha = shape[4] if len(shape) > 4 else ""
+            scoped = bool(shape[6]) if len(shape) > 6 else False
             key = (path, name, kind)
             if key in seen:
                 continue
             seen.add(key)
             row = by_key.get(key)
             if row is None:
-                session.add(CodeShape(
+                row = CodeShape(
                     project_id=project_id, repo_key=repo_key,
                     path=path, symbol=name, kind=kind,
                     first_seen_commit=seen_marker, last_seen_commit=seen_marker,
                     signature=signature, body_sha=body_sha,
-                ))
+                )
+                if scoped:
+                    await _judge(session, row, status="scoped", snippet_id=None,
+                                 by="mechanical", reason=_SCOPED_REASON, at=now)
+                else:
+                    session.add(row)
                 continue
             row.last_seen_commit = seen_marker
+            if scoped and row.status == "unclassified":
+                await _judge(session, row, status="scoped", snippet_id=None,
+                             by="mechanical", reason=_SCOPED_REASON, at=now)
+            elif not scoped and row.status == "scoped":
+                await _judge(session, row, status="unclassified", snippet_id=None,
+                             by=None, reason=None, at=now)
             if signature:
                 row.signature = signature
             if body_sha and body_sha != row.body_sha:
@@ -158,7 +183,7 @@ def _event(row: CodeShape, event: str, at: datetime, *, commit: str = "") -> Cod
 
 async def _judge(
     session, row: CodeShape, *, status: str, snippet_id: int | None,
-    by: str | None, reason: str | None, at: datetime,
+    by: str | None, reason: str | None, at: datetime, reason_code: str | None = None,
 ) -> None:
     """Apply a judgment to a row — the ONE place a status is set — and write
     its history. Clears what a judgment settles: the standing proposal, the
@@ -169,6 +194,7 @@ async def _judge(
     row.status = status
     row.snippet_id = snippet_id if status in _NEEDS_TARGET else None
     row.reason = (reason or "").strip() or None
+    row.reason_code = (reason_code or "").strip() or None
     row.classified_by = by if status != "unclassified" else None
     row.classified_at = at if status != "unclassified" else None
     row.classified_sha = row.body_sha if status != "unclassified" else ""
@@ -183,6 +209,59 @@ async def _judge(
     session.add(_event(row, "classified", at))
 
 
+async def record_uses(
+    session, row: CodeShape, snippet_ids, *, basis: str, evidence: str | None = None,
+) -> int:
+    """Upsert consumption edges shape → snippet (#2870). A judgment-grade
+    basis (agent/audit/import) overwrites a mechanical one (reference/hook)
+    on the same edge; mechanical never overwrites a judgment. Returns the
+    number of edges written or refreshed. The row must be persisted (flushed)
+    so it has an id."""
+    wanted = {int(x) for x in (snippet_ids or []) if x}
+    if not wanted:
+        return 0
+    if row.id is None:
+        session.add(row)
+        await session.flush()
+    existing = {
+        e.snippet_id: e
+        for e in (
+            await session.execute(
+                select(CodeShapeUse).where(CodeShapeUse.shape_id == row.id)
+            )
+        ).scalars().all()
+    }
+    judged = basis in _CALLER_VIAS
+    n = 0
+    for sid in wanted:
+        edge = existing.get(sid)
+        if edge is None:
+            session.add(CodeShapeUse(shape_id=row.id, snippet_id=sid, basis=basis, evidence=evidence))
+            n += 1
+        elif judged or edge.basis not in _CALLER_VIAS:
+            edge.basis, edge.evidence = basis, evidence
+            n += 1
+    return n
+
+
+async def uses_of(shape_ids) -> dict[int, list[CodeShapeUse]]:
+    """{shape_id: [edges]} for a set of rows — the read side of record_uses."""
+    ids = [int(x) for x in shape_ids if x]
+    if not ids:
+        return {}
+    async with async_session() as session:
+        edges = (
+            await session.execute(
+                select(CodeShapeUse).where(CodeShapeUse.shape_id.in_(ids))
+                .order_by(CodeShapeUse.shape_id, CodeShapeUse.snippet_id)
+            )
+        ).scalars().all()
+    out: dict[int, list[CodeShapeUse]] = {}
+    for e in edges:
+        out.setdefault(e.shape_id, []).append(e)
+    return out
+
+
 async def mark_canonicals(
     project_id: int, recorded: list[tuple[int, str, str]]
 ) -> None:
@@ -214,7 +293,7 @@ async def mark_canonicals(
                 ),
                 None,
             )
-            if covering is not None and row.status == "unclassified":
+            if covering is not None and row.status in _MECHANICAL_TODO:
                 await _judge(session, row, status="canonical", snippet_id=covering,
                              by="mechanical", reason=None, at=now)
             elif (
@@ -289,6 +368,17 @@ def validate_classifications(items: list[dict]) -> str | None:
                 f"classifications[{i}]: status {status!r} needs a reason — "
                 "the WHY is the record (note 2786)"
             )
+        code = (item.get("reason_code") or "").strip()
+        if code and code not in REASON_CODES:
+            return (
+                f"classifications[{i}]: unknown reason_code {code!r} "
+                f"(one of: {', '.join(REASON_CODES)})"
+            )
+        uses = item.get("uses")
+        if uses is not None and (
+            not isinstance(uses, list) or not all(isinstance(u, int) and u > 0 for u in uses)
+        ):
+            return f"classifications[{i}]: uses must be a list of snippet ids"
     return None
 
 
@@ -327,6 +417,8 @@ async def classify_shapes(
         for item in classifications
         if item.get("status") in _NEEDS_TARGET
     }
+    for item in classifications:
+        target_ids.update(int(u) for u in (item.get("uses") or []))
     for sid in sorted(target_ids):
         if await snippets_svc.get_snippet(user_id, sid) is None:
             raise ValueError(f"snippet {sid} not found (or not readable)")
@@ -364,12 +456,101 @@ async def classify_shapes(
                     session, row, status=status,
                     snippet_id=int(item["snippet_id"]) if status in _NEEDS_TARGET else None,
                     by=via, reason=item.get("reason"), at=now,
+                    reason_code=item.get("reason_code"),
                 )
+                if item.get("uses"):
+                    await record_uses(session, row, item["uses"], basis=via,
+                                      evidence=item.get("reason"))
                 classified += 1
         await session.commit()
     return {"classified": classified, "unmatched": unmatched}
 
 
+def rule_matches(row: CodeShape, *, path: str, pattern: str, kind: str) -> bool:
+    """Does a ledger row fall under a rule-form classification (#2868)?
+    ``path`` is a file or a directory (everything beneath it), ``pattern``
+    a shell glob on the symbol (``""`` = every symbol), ``kind`` narrows to
+    sym/css. Pure, so the sweep's reach can be tested without a database."""
+    import fnmatch
+
+    clean = (path or "").strip().strip("/")
+    if clean and not (row.path == clean or row.path.startswith(clean + "/")):
+        return False
+    if kind and row.kind != kind:
+        return False
+    if pattern and not fnmatch.fnmatchcase(_norm_symbol(row.symbol), pattern):
+        return False
+    return True
+
+
+async def classify_shapes_where(
+    user_id: int,
+    project_id: int,
+    *,
+    path: str,
+    status: str,
+    pattern: str = "",
+    kind: str = "",
+    snippet_id: int | None = None,
+    reason: str | None = None,
+    via: str = "agent",
+    include_judged: bool = False,
+    reason_code: str | None = None,
+    uses: list[int] | None = None,
+) -> dict:
+    """The sweep form of classify_shapes (#2868): one judgment applied to
+    every live row under ``path`` whose symbol matches ``pattern`` (and
+    ``kind``). By default only unjudged rows are touched — `unclassified`
+    and the sync's mechanical `scoped` stamp — a sweep must never silently
+    overwrite a judgment; ``include_judged`` opts in.
+    Same gates as the row form (status vocabulary, snippet target, reason
+    for variant/exempt, write access); one transaction, so it applies whole
+    or not at all. Returns the count and a sample of what it judged."""
+    from scribe.services import access
+    from scribe.services import snippets as snippets_svc
+
+    if via not in _CALLER_VIAS:
+        raise ValueError(f"via must be one of: {', '.join(_CALLER_VIAS)}")
+    if not (path or "").strip():
+        raise ValueError("path is required — a sweep names the directory it judges")
+    if status == "canonical":
+        raise ValueError("canonical is the sync's stamp on a snippet's own location — a sweep cannot set it")
+    probe = {"path": path, "symbol": "*", "status": status,
+             "snippet_id": snippet_id or 0, "reason": reason or "",
+             "reason_code": reason_code or "", "uses": uses}
+    error = validate_classifications([probe])
+    if error:
+        raise ValueError(error.replace("classifications[0]", "rule"))
+    if not await access.can_write_project(user_id, project_id):
+        raise ValueError(f"project {project_id} not found or no write access")
+    if status in _NEEDS_TARGET and await snippets_svc.get_snippet(user_id, int(snippet_id)) is None:
+        raise ValueError(f"snippet {snippet_id} not found (or not readable)")
+    for sid in sorted({int(u) for u in (uses or [])}):
+        if await snippets_svc.get_snippet(user_id, sid) is None:
+            raise ValueError(f"snippet {sid} not found (or not readable)")
+
+    now = datetime.now(timezone.utc)
+    judged: list[str] = []
+    async with async_session() as session:
+        conds = [CodeShape.project_id == project_id, CodeShape.vanished_at.is_(None)]
+        if not include_judged:
+            conds.append(CodeShape.status.in_(_MECHANICAL_TODO))
+        rows = (await session.execute(select(CodeShape).where(*conds))).scalars().all()
+        for row in rows:
+            if not rule_matches(row, path=path, pattern=pattern, kind=kind):
+                continue
+            await _judge(
+                session, row, status=status,
+                snippet_id=int(snippet_id) if status in _NEEDS_TARGET else None,
+                by=via, reason=reason, at=now, reason_code=reason_code,
+            )
+            if uses:
+                await record_uses(session, row, uses, basis=via, evidence=reason)
+            judged.append(f"{row.path}::{row.symbol}")
+        await session.commit()
+    return {"classified": len(judged), "sample": sorted(judged)[:12]}
+
+
 async def list_project_shapes(
     user_id: int,
     project_id: int,
@@ -382,6 +563,7 @@ async def list_project_shapes(
     offset: int = 0,
     proposal: str = "",
     flag: str = "",
+    uses: int = 0,
 ) -> tuple[list[CodeShape], int]:
     """A filtered page of a project's ledger, with the unfiltered-match total.
 
@@ -427,6 +609,12 @@ async def list_project_shapes(
         conds.append(CodeShape.diverges_from.isnot(None))
     elif flag == "recheck":
         conds.append(CodeShape.recheck_at.isnot(None))
+    if uses:
+        # Consumers of a canon (#2870): rows with a uses edge to it, whatever
+        # shape they themselves are.
+        conds.append(CodeShape.id.in_(
+            select(CodeShapeUse.shape_id).where(CodeShapeUse.snippet_id == uses)
+        ))
     async with async_session() as session:
         total = (
             await session.execute(
@@ -477,18 +665,38 @@ async def snippet_consumers(user_id: int, note_id: int) -> dict:
                 )
             )
         ).scalars().all()
-    readable: dict[int, bool] = {}
-    out: dict[str, list[dict]] = {"instances": [], "variants": []}
-    for row in rows:
-        if row.project_id not in readable:
-            readable[row.project_id] = await access.can_read_project(
-                user_id, row.project_id
+        # The consumption edges (#2870): rows that USE this canon, whatever
+        # shape they are themselves — the call-site map.
+        using = (
+            await session.execute(
+                select(CodeShape, CodeShapeUse.basis, CodeShapeUse.evidence)
+                .join(CodeShapeUse, CodeShapeUse.shape_id == CodeShape.id)
+                .where(CodeShapeUse.snippet_id == note_id, CodeShape.vanished_at.is_(None))
             )
-        if not readable[row.project_id]:
+        ).all()
+    readable: dict[int, bool] = {}
+
+    async def can_read(pid: int) -> bool:
+        if pid not in readable:
+            readable[pid] = await access.can_read_project(user_id, pid)
+        return readable[pid]
+
+    out: dict[str, list[dict]] = {"instances": [], "variants": [], "uses": []}
+    for row in rows:
+        if not await can_read(row.project_id):
             continue
         out["instances" if row.status == "instance" else "variants"].append(
             _consumer_dict(row)
         )
+    for row, basis, evidence in using:
+        if not await can_read(row.project_id):
+            continue
+        d = _consumer_dict(row)
+        d["basis"] = basis
+        if evidence:
+            d["evidence"] = evidence
+        d.pop("reason", None)
+        out["uses"].append(d)
     return out
 
 
@@ -660,7 +868,7 @@ async def stamp_write_path_instances(
                 )
                 session.add(row)
                 by_key[(name, kind)] = row
-            elif not (row.status == "unclassified" or row.classified_by == "hook"):
+            elif not (row.status in _MECHANICAL_TODO or row.classified_by == "hook"):
                 continue  # a judgment — or the canon itself — stands
             await _judge(session, row, status="instance", snippet_id=sid, by="hook",
                          reason=why, at=now)
@@ -668,6 +876,13 @@ async def stamp_write_path_instances(
                 "path": path, "symbol": name, "kind": kind,
                 "snippet_id": sid, "reason": why,
             })
+            # Every pulled canon the payload NAMES is a uses edge (#2870) — the
+            # call-site fact, independent of which one the row is judged to be.
+            await record_uses(
+                session, row,
+                [s_id for rank, _at, s_id, _why in bucket if rank == 2],
+                basis="hook", evidence="write path: pulled the snippet, payload names its symbol",
+            )
         if stamped:
             await session.commit()
     return stamped
@@ -718,7 +933,9 @@ _SEMANTIC_CAP = 150
 _SEMANTIC_FLOOR = 0.8
 # Bump when a basis's rule changes: rows remember the (body, ruleset) they
 # were examined under, so a tightened rule re-examines everything once.
-_PROPOSER_VERSION = 2
+# v3: language-family gate on the sym bases, reference stoplist, semantic
+# restricted to the shape's own project (#2871).
+_PROPOSER_VERSION = 3
 # Signature resemblance floor, name blanked (difflib ratio) — and a length
 # floor, because `def NAME():` resembles `def NAME(x):` at 0.95 while saying
 # nothing; a family shape has parameters to resemble.
@@ -737,6 +954,64 @@ class Canon(NamedTuple):
     signature: str
     code_norm: str
     project_id: int = 0
+    language: str = ""   # the snippet's recorded language; "" = unknown, no gate
+
+
+# Language families: the sym bases only propose within one. The 2026-08
+# audit (#2871) found every cross-language hit wrong — a Python tool-module
+# canon named `register` proposed for Vue `handleSubmit`s that call
+# `authStore.register()`, and a TS store's `register` matched it by symbol;
+# Minstrel/Forge TS canon proposed for Python bodies by resemblance. CSS is
+# its own kind and is not gated here.
+_FAMILY_BY_LANG = {
+    "python": "py", "py": "py",
+    "typescript": "js", "ts": "js", "tsx": "js", "javascript": "js", "js": "js",
+    "jsx": "js", "vue": "js", "mjs": "js", "cjs": "js",
+    "css": "css", "scss": "css", "sass": "css", "less": "css",
+    "bash": "sh", "sh": "sh", "shell": "sh", "zsh": "sh",
+    "sql": "sql",
+}
+_FAMILY_BY_EXT = {
+    ".py": "py", ".pyi": "py",
+    ".ts": "js", ".tsx": "js", ".js": "js", ".jsx": "js", ".vue": "js", ".mjs": "js", ".cjs": "js",
+    ".css": "css", ".scss": "css", ".sass": "css", ".less": "css",
+    ".sh": "sh", ".bash": "sh", ".zsh": "sh",
+    ".sql": "sql",
+}
+
+
+def language_family(language: str) -> str:
+    """The family a recorded snippet language belongs to ("" when unknown)."""
+    return _FAMILY_BY_LANG.get((language or "").strip().lower(), "")
+
+
+def path_family(path: str) -> str:
+    """The family a file path belongs to, by extension ("" when unknown)."""
+    p = (path or "").lower()
+    for ext, fam in _FAMILY_BY_EXT.items():
+        if p.endswith(ext):
+            return fam
+    return ""
+
+
+def same_family(path: str, canon_language: str) -> bool:
+    """A sym basis may propose this canon for this path: both families known
+    and equal, or either unknown (no evidence either way → no gate)."""
+    a = path_family(path)
+    b = language_family(canon_language)
+    return not a or not b or a == b
+
+
+# Reference basis: generic verbs name too many unrelated things to count a
+# bare mention as a call site of THIS canon (`register`, `load`, `save` …).
+# The symbol basis still catches a second definition of such a name; the
+# call-site relation for these becomes a `uses` edge once #2870 lands.
+_REFERENCE_STOPLIST = frozenset({
+    "get", "set", "put", "post", "load", "save", "run", "main", "init", "setup",
+    "register", "restore", "reset", "toggle", "close", "open", "submit", "handler",
+    "update", "create", "delete", "remove", "add", "start", "stop", "send",
+    "receive", "render", "mount", "dispatch", "call", "apply", "execute",
+})
 
 
 def _norm_text(text: str) -> str:
@@ -768,6 +1043,26 @@ def text_contains(body: str, code: str) -> bool:
     return a in b or b in a
 
 
+def reference_canons(kind: str, path: str, symbol: str, body: str, canons: Iterable[Canon]) -> list[int]:
+    """Every canon this body NAMES (#2870) — the uses edges the proposer can
+    write mechanically: same kind, same language family, symbol not in the
+    generic-verb stoplist, and not the shape's own name."""
+    norm_sym = _norm_symbol(symbol)
+    out: list[int] = []
+    for c in canons:
+        if c.kind != kind or not c.symbol:
+            continue
+        if kind == "sym" and not same_family(path, c.language):
+            continue
+        if _norm_symbol(c.symbol) == norm_sym:
+            continue
+        if _norm_symbol(c.symbol).lower() in _REFERENCE_STOPLIST:
+            continue
+        if references_symbol(body, c.symbol, kind):
+            out.append(c.snippet_id)
+    return out
+
+
 def match_canon(
     kind: str, path: str, symbol: str, signature: str, body: str,
     canons: Iterable[Canon], *, project_id: int = 0,
@@ -789,11 +1084,17 @@ def match_canon(
     for c in canons:
         if c.kind != kind:
             continue
+        if kind == "sym" and not same_family(path, c.language):
+            continue  # a Python canon says nothing about a Vue body, and vice versa
         if c.symbol and _norm_symbol(c.symbol) == norm_sym:
             if not any(location_covers(lp, ls, path, symbol) for lp, ls in c.locations):
                 offer("symbol", 1.0, c)
             continue  # its own location is canonical territory, not a proposal
-        if c.symbol and references_symbol(body, c.symbol, kind):
+        if (
+            c.symbol
+            and _norm_symbol(c.symbol).lower() not in _REFERENCE_STOPLIST
+            and references_symbol(body, c.symbol, kind)
+        ):
             offer("reference", 0.9, c)
         if c.code_norm and text_contains(body, c.code_norm):
             offer("text", 0.95, c)
@@ -849,6 +1150,7 @@ async def canon_catalog(user_id: int) -> list[Canon]:
                 for loc in fields.get("locations") or []
             ),
             signature, _norm_text(code), int(note.project_id or 0),
+            (fields.get("language") or "").strip().lower(),
         ))
     return out
 
@@ -907,7 +1209,14 @@ async def propose_for_repo(
     if canons is None:
         canons = await canon_catalog(user_id)
     by_key = {(d[0], d[1], d[2]): d for d in definitions}
-    sym_canon_ids = {c.snippet_id for c in canons if c.kind == "sym"}
+    # The semantic arm is the widest net and, across projects, was pure noise
+    # in the 2026-08 audit (#2871): it is held to the shape's own project and
+    # language family. The precise bases (symbol/text) still reach family
+    # canon in other projects (note 2786).
+    sym_canons = [c for c in canons if c.kind == "sym" and c.project_id == project_id]
+
+    def semantic_allowed(path: str) -> set[int]:
+        return {c.snippet_id for c in sym_canons if same_family(path, c.language)}
     now = datetime.now(timezone.utc)
     examined = proposed = checked = 0
     async with async_session() as session:
@@ -916,7 +1225,6 @@ async def propose_for_repo(
                 select(CodeShape).where(
                     CodeShape.project_id == project_id,
                     CodeShape.repo_key == repo_key,
-                    CodeShape.status == "unclassified",
                     CodeShape.vanished_at.is_(None),
                 )
             )
@@ -930,6 +1238,18 @@ async def propose_for_repo(
             examined_as = f"{body_sha}@{_PROPOSER_VERSION}"
             if row.proposed_at is not None and row.proposed_sha == examined_as:
                 continue
+            if row.status not in _MECHANICAL_TODO:
+                # A judged row gets no proposal — but its uses edges (#2870)
+                # are a fact about the body, judged or not: the consumer map
+                # of a canon must include the call sites someone already
+                # classified. Mark it examined so the scan runs once per body.
+                used = reference_canons(row.kind, row.path, row.symbol, body, canons)
+                if used:
+                    await record_uses(session, row, used, basis="reference",
+                                      evidence="proposer: body names the canon's symbol")
+                row.proposed_at = now
+                row.proposed_sha = examined_as
+                continue
             examined += 1
             group = row.proposal_group  # derive grouping is reassigned below
             hit = match_canon(
@@ -940,6 +1260,12 @@ async def propose_for_repo(
             row.proposal_group = group
             row.proposed_at = now
             row.proposed_sha = examined_as
+            # Consumption is recorded for every canon the body names (#2870),
+            # whatever the row is then judged to be.
+            used = reference_canons(row.kind, row.path, row.symbol, body, canons)
+            if used:
+                await record_uses(session, row, used, basis="reference",
+                                  evidence="proposer: body names the canon's symbol")
             if hit:
                 row.proposed_snippet_id, row.proposal_basis, row.proposal_score = hit
                 row.proposal_group = None
@@ -955,7 +1281,7 @@ async def propose_for_repo(
                 continue
             checked += 1
             try:
-                found = await _semantic_canon(user_id, d[5], sym_canon_ids)
+                found = await _semantic_canon(user_id, d[5], semantic_allowed(row.path))
             except Exception:
                 logger.warning("semantic proposal failed", exc_info=True)
                 found = None
@@ -1005,7 +1331,7 @@ async def apply_derive_groups(project_id: int) -> int:
             await session.execute(
                 select(CodeShape).where(
                     CodeShape.project_id == project_id,
-                    CodeShape.status == "unclassified",
+                    CodeShape.status.in_(_MECHANICAL_TODO),
                     CodeShape.vanished_at.is_(None),
                     CodeShape.proposed_snippet_id.is_(None),
                 )
@@ -1038,27 +1364,44 @@ def proposal_summary(rows: Iterable[CodeShape], *, top: int = 8) -> dict:
     """The readout's view of the proposer's standing: how many canon
     proposals await confirmation, and the largest derive-first groups."""
     proposed = 0
+    by_canon: dict[int, int] = {}
     groups: dict[str, dict] = {}
+    files: dict[str, set[str]] = {}
     for row in rows:
-        if row.status != "unclassified":
+        if row.status not in _MECHANICAL_TODO:
             continue
         if row.proposed_snippet_id is not None:
             proposed += 1
+            by_canon[row.proposed_snippet_id] = by_canon.get(row.proposed_snippet_id, 0) + 1
         elif row.proposal_group:
+            dup = not row.proposal_group.startswith("name:")
             g = groups.setdefault(row.proposal_group, {
                 "group": row.proposal_group, "kind": row.kind,
                 "label": (
-                    ("." if row.kind == "css" else "") + row.symbol
-                    if row.proposal_group.startswith("name:")
-                    else f"{row.symbol} (identical body)"
+                    f"{row.symbol} (identical body)" if dup
+                    else ("." if row.kind == "css" else "") + row.symbol
                 ),
-                "size": 0, "paths": [],
+                "size": 0, "files": 0, "paths": [],
             })
             g["size"] += 1
+            files.setdefault(row.proposal_group, set()).add(row.path)
             if len(g["paths"]) < 3:
                 g["paths"].append(row.path)
-    ranked = sorted(groups.values(), key=lambda g: (-g["size"], g["group"]))
-    return {"proposed": proposed, "derive_groups": ranked[:top]}
+    for key, g in groups.items():
+        g["files"] = len(files[key])
+    # Body-identical groups first (#2872): the things an audit actually
+    # consolidated were identical bodies under different names/files; a
+    # name repeated across modules is usually convention. Within a tier,
+    # the group spread over more files is the bigger copy.
+    ranked = sorted(
+        groups.values(),
+        key=lambda g: (g["group"].startswith("name:"), -g["files"], -g["size"], g["group"]),
+    )
+    top_canon = None
+    if by_canon:
+        sid, n = max(by_canon.items(), key=lambda kv: (kv[1], -kv[0]))
+        top_canon = {"snippet_id": sid, "count": n}
+    return {"proposed": proposed, "derive_groups": ranked[:top], "top_canon": top_canon}
 
 
 async def confirm_proposals(
@@ -1089,7 +1432,7 @@ async def confirm_proposals(
 
     conds = [
         CodeShape.project_id == project_id,
-        CodeShape.status == "unclassified",
+        CodeShape.status.in_(_MECHANICAL_TODO),
         CodeShape.vanished_at.is_(None),
         CodeShape.proposed_snippet_id.isnot(None),
     ]
@@ -1246,7 +1589,7 @@ async def flag_divergence(project_id: int, *, since: datetime | None) -> int:
         for siblings in by_dir.values():
             dom = dominant_canon(siblings)
             for r in siblings:
-                if r.status != "unclassified":
+                if r.status not in _MECHANICAL_TODO:
                     continue
                 if r.diverges_from is not None:
                     flagged += 1
@@ -1263,7 +1606,7 @@ async def flag_divergence(project_id: int, *, since: datetime | None) -> int:
 
 def divergence_summary(rows: Iterable[CodeShape], *, top: int = 10) -> dict:
     """Readout view: flagged shapes (newest first) and the recheck count."""
-    flagged = [r for r in rows if r.diverges_from is not None and r.status == "unclassified"]
+    flagged = [r for r in rows if r.diverges_from is not None and r.status in _MECHANICAL_TODO]
     flagged.sort(key=lambda r: (r.created_at or datetime.min.replace(tzinfo=timezone.utc)), reverse=True)
     recheck = sum(1 for r in rows if r.recheck_at is not None and r.vanished_at is None)
     return {

src/scribe/services/systems.py

@@ -18,6 +18,41 @@ from scribe.services import access
 logger = logging.getLogger(__name__)
 
 
+# The standard cross-project vocabulary (#2798): names that mean the same
+# thing in every project, so a starter set reads the same everywhere. The
+# bootstrap ask (mcp/tools/systems) names them; the inception seed
+# (services/inception, milestone 297) mints them. Charters are deliberately
+# generic — a project refines them as its own records accrue.
+STANDARD_SYSTEMS: tuple[tuple[str, str], ...] = (
+    ("CI & Release", "How the project is verified and shipped: pipelines, runners, image/artifact builds, release tagging and rollback."),
+    ("Auth & Access", "Who may do what: identity, sessions/tokens, permissions and the scoping of every read and write to the right users."),
+    ("Data Model & Storage", "What is stored and how it is shaped: the schema, migrations, serialisation and the services that own a table's lifecycle."),
+    ("API Surface", "The doors into the capability: HTTP routes, tool/RPC surfaces, request parsing, error envelopes and their contracts."),
+    ("UI & Design", "What people see and touch: views, components, client state, and the design tokens/recipes they are built from."),
+    ("Import & Export", "Data crossing the boundary: backups, exports, imports, sync with other systems, file formats."),
+    ("Background Jobs", "Work that runs without a request: schedulers, queues, periodic ticks, retention and maintenance."),
+    ("Observability", "How the system reports on itself: logging, metrics, audit trails, health and diagnostics."),
+)
+
+
+async def seed_standard_systems(user_id: int, project_id: int) -> list[System]:
+    """Mint the standard starter set for a project that has NO Systems yet
+    (milestone 297). Idempotent: a project with any System — the vocabulary
+    already started, standard or not — gets nothing; the duplicate gate and
+    the project's own judgment take it from there. [] without write access."""
+    if await list_systems(user_id, project_id, include_archived=True):
+        return []
+    out: list[System] = []
+    for index, (name, charter) in enumerate(STANDARD_SYSTEMS):
+        system = await create_system(
+            user_id, project_id, name, description=charter, order_index=index,
+        )
+        if system is None:
+            break
+        out.append(system)
+    return out
+
+
 async def create_system(
     user_id: int,
     project_id: int,

tests/test_inception.py

@@ -0,0 +1,65 @@
+"""Project inception (milestone 297) — step 1: the record's shape.
+
+The WHY a project inherits what it does lives on projects.inception; the
+opt-out of an always-on rulebook is its own association table. Pure
+validation is pinned here; the effects are step 3's integration tests.
+"""
+from scribe.models import Base
+from scribe.models.project import Project
+from scribe.models.rulebook import project_rulebook_exclusions
+from scribe.services.inception import (
+    CHOICE_KEYS, INCEPTION_VIAS, is_decided, normalize_choices, validate_inception,
+)
+
+
+def test_project_carries_an_inception_record_and_to_dict_shows_it():
+    assert "inception" in Project.__table__.c
+    assert Project.__table__.c.inception.nullable   # NULL = undecided
+    p = Project(user_id=1, title="x", inception=None)
+    assert p.to_dict()["inception"] is None and not is_decided(p)
+    p.inception = {"via": "mcp", "decided_at": "2026-08-22T00:00:00+00:00", "decided_by": 1,
+                   "choices": normalize_choices({"seed_systems": True})}
+    assert is_decided(p) and p.to_dict()["inception"]["via"] == "mcp"
+    assert INCEPTION_VIAS == ("mcp", "ui", "legacy")
+
+
+def test_exclusions_table_is_the_suppressions_sibling():
+    t = Base.metadata.tables["project_rulebook_exclusions"]
+    assert project_rulebook_exclusions is t
+    assert {c.name for c in t.primary_key.columns} == {"project_id", "rulebook_id"}
+    fks = {fk.column.table.name: fk.ondelete for c in t.columns for fk in c.foreign_keys}
+    assert fks == {"projects": "CASCADE", "rulebooks": "CASCADE"}
+
+
+def test_validate_inception_pins_the_choice_vocabulary():
+    assert CHOICE_KEYS == ("exclude_always_on_rulebooks", "subscribe_rulebooks", "design_system_id", "seed_systems")
+    assert validate_inception({}) is None
+    assert validate_inception({"exclude_always_on_rulebooks": [1], "subscribe_rulebooks": [2],
+                               "design_system_id": 3, "seed_systems": True}) is None
+    assert validate_inception({"design_system_id": None}) is None
+    assert "must be an object" in validate_inception([])
+    assert "unknown inception choice" in validate_inception({"repo": "x"})
+    assert "list of rulebook ids" in validate_inception({"exclude_always_on_rulebooks": "1"})
+    assert "list of rulebook ids" in validate_inception({"subscribe_rulebooks": [0]})
+    assert "list of rulebook ids" in validate_inception({"subscribe_rulebooks": [True]})
+    assert "both excluded and subscribed" in validate_inception(
+        {"exclude_always_on_rulebooks": [1, 2], "subscribe_rulebooks": [2]})
+    assert "positive id or null" in validate_inception({"design_system_id": 0})
+    assert "positive id or null" in validate_inception({"design_system_id": True})
+    assert "true or false" in validate_inception({"seed_systems": "yes"})
+
+
+def test_normalize_choices_is_canonical_and_complete():
+    out = normalize_choices({"subscribe_rulebooks": [3, 1, 3], "exclude_always_on_rulebooks": [2]})
+    assert out == {"exclude_always_on_rulebooks": [2], "subscribe_rulebooks": [1, 3],
+                   "design_system_id": None, "seed_systems": False}
+    assert normalize_choices(None) == {"exclude_always_on_rulebooks": [], "subscribe_rulebooks": [],
+                                       "design_system_id": None, "seed_systems": False}
+
+
+def test_standard_systems_vocabulary_is_one_list_for_ask_and_seed():
+    from scribe.mcp.tools.systems import _STANDARD_SYSTEMS
+    from scribe.services.systems import STANDARD_SYSTEMS
+    assert _STANDARD_SYSTEMS == tuple(n for n, _ in STANDARD_SYSTEMS)
+    assert len(STANDARD_SYSTEMS) == 8 and all(charter for _, charter in STANDARD_SYSTEMS)
+

tests/test_inception_rules.py

@@ -0,0 +1,66 @@
+"""Milestone 297 step 2 — always-on exclusions reach every rule surface.
+
+The SQL is the integration lane's; here the contracts: rules_payload carries
+the seventh key, list_always_on_rules takes project_id, the session-start
+block names the excluded rulebooks, and the MCP tools mount.
+"""
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from scribe.services.rulebooks import rules_payload
+
+
+def test_rules_payload_carries_excluded_always_on_as_the_seventh_key():
+    out = rules_payload({
+        "rules": [], "truncated": False, "subscribed_rulebooks": [],
+        "excluded_always_on": [{"id": 1, "title": "Family"}],
+    })
+    assert set(out) == {
+        "applicable_rules", "applicable_rules_truncated", "subscribed_rulebooks",
+        "project_rules", "suppressed_rules", "suppressed_topics", "excluded_always_on",
+    }
+    assert out["excluded_always_on"] == [{"id": 1, "title": "Family"}]
+    # An older applicable dict without the key still renders (empty list).
+    assert rules_payload({"rules": [], "truncated": False, "subscribed_rulebooks": []})["excluded_always_on"] == []
+
+
+def test_list_always_on_rules_service_and_tool_take_a_project_id():
+    import inspect
+
+    from scribe.mcp.tools import rulebooks as tools
+    from scribe.services import rulebooks as svc
+    assert "project_id" in inspect.signature(svc.list_always_on_rules).parameters
+    assert "project_id" in inspect.signature(tools.list_always_on_rules).parameters
+
+
+@pytest.mark.asyncio
+async def test_session_context_names_the_excluded_always_on_rulebooks():
+    from types import SimpleNamespace as NS
+
+    from scribe.services.plugin_context import build_session_context
+    rules = [NS(id=1, title="`dev` is home", topic_id=1, statement="x")]
+    project = NS(id=9, title="Widget", goal="", design_system_id=None)
+    with patch("scribe.services.plugin_context.rulebooks_svc.list_always_on_rules",
+               AsyncMock(return_value=rules)) as lao, \
+         patch("scribe.services.plugin_context.rulebooks_svc.excluded_always_on_rulebooks",
+               AsyncMock(return_value=[{"id": 5, "title": "Design standards"}])), \
+         patch("scribe.services.plugin_context._topic_titles", AsyncMock(return_value={1: "git"})), \
+         patch("scribe.services.plugin_context.projects_svc.get_project", AsyncMock(return_value=project)), \
+         patch("scribe.services.plugin_context.notes_svc.list_notes", AsyncMock(return_value=([], 0))), \
+         patch("scribe.services.plugin_context.rulebooks_svc.get_applicable_rules",
+               AsyncMock(return_value={"rules": [], "truncated": False, "subscribed_rulebooks": [],
+                                       "project_rules": [], "suppressed_rules": [],
+                                       "suppressed_topics": [], "excluded_always_on": []})):
+        out = await build_session_context(user_id=7, project_id=9)
+    # The always-on set was asked FOR THIS PROJECT, and the departure is named.
+    assert lao.await_args.kwargs.get("project_id") == 9
+    assert "Excluded for this project by its inception decision" in out["context"]
+    assert "Design standards (#5)" in out["context"]
+
+
+def test_exclusion_routes_are_registered():
+    from scribe.app import create_app
+    rules = {r.rule for r in create_app().url_map.iter_rules()}
+    assert "/api/projects/<int:project_id>/exclusions/rulebooks/<int:rulebook_id>" in rules
+

tests/test_integration_inception.py

@@ -0,0 +1,111 @@
+"""Real-Postgres integration tests for project inception (milestone 297).
+
+What mocks can't prove: a decision's effects land through the real services
+(exclusions filter the always-on set, subscriptions bind, the design system
+points, the standard Systems seed once), the record is written last, a bad
+target applies nothing.
+"""
+import pytest
+import pytest_asyncio
+
+from scribe.models import async_session
+from scribe.models.project import Project
+from scribe.models.rulebook import Rulebook
+from scribe.services import inception as inception_svc
+from scribe.services import rulebooks as rulebooks_svc
+from scribe.services import systems as systems_svc
+from tests.helpers import ensure_user
+
+pytestmark = [pytest.mark.integration, pytest.mark.usefixtures("_dispose_engine")]
+
+
+@pytest_asyncio.fixture
+async def seeded():
+    """Owner, a fresh project, one always-on rulebook (with a rule) and one
+    ordinary rulebook (with a rule)."""
+    async with async_session() as s:
+        owner = await ensure_user(s, "inception_owner")
+        project = Project(user_id=owner.id, title="Inception target")
+        s.add(project)
+        await s.flush()
+        ids = {"owner": owner.id, "pid": project.id}
+        await s.commit()
+    always = await rulebooks_svc.create_rulebook(ids["owner"], "Family standards")
+    other = await rulebooks_svc.create_rulebook(ids["owner"], "Optional practices")
+    async with async_session() as s:
+        rb = await s.get(Rulebook, always.id)
+        rb.always_on = True
+        await s.commit()
+    t1 = await rulebooks_svc.create_topic(always.id, ids["owner"], "git")
+    await rulebooks_svc.create_rule(t1.id, ids["owner"], "dev is home", "Work on dev.")
+    t2 = await rulebooks_svc.create_topic(other.id, ids["owner"], "docs")
+    await rulebooks_svc.create_rule(t2.id, ids["owner"], "Write the why", "Record reasons.")
+    ids.update({"always": always.id, "other": other.id})
+    return ids
+
+
+@pytest.mark.integration
+async def test_decide_applies_every_effect_and_records_last(seeded):
+    owner, pid = seeded["owner"], seeded["pid"]
+    # Undecided: the always-on rulebook binds, nothing subscribed, no Systems.
+    assert [r.title for r in await rulebooks_svc.list_always_on_rules(owner, project_id=pid)] == ["dev is home"]
+    defaults = await inception_svc.current_defaults(owner, pid)
+    assert [r["id"] for r in defaults["always_on_rulebooks"]] == [seeded["always"]]
+    assert [r["id"] for r in defaults["other_rulebooks"]] == [seeded["other"]]
+    assert defaults["systems"] == 0 and defaults["design_system_id"] is None
+
+    out = await inception_svc.decide(owner, pid, via="mcp", choices={
+        "exclude_always_on_rulebooks": [seeded["always"]],
+        "subscribe_rulebooks": [seeded["other"]],
+        "design_system_id": None,
+        "seed_systems": True,
+    })
+    assert out["effects"]["excluded"] == [seeded["always"]]
+    assert out["effects"]["subscribed"] == [seeded["other"]]
+    assert len(out["effects"]["systems_seeded"]) == len(systems_svc.STANDARD_SYSTEMS)
+
+    # The exclusion is total: the project's always-on set is empty, the
+    # departure is named, the subscription binds.
+    assert await rulebooks_svc.list_always_on_rules(owner, project_id=pid) == []
+    assert len(await rulebooks_svc.list_always_on_rules(owner)) == 1   # user-wide unchanged
+    applicable = await rulebooks_svc.get_applicable_rules(pid, owner)
+    assert [r["title"] for r in applicable["rules"]] == ["Write the why"]
+    assert [e["id"] for e in applicable["excluded_always_on"]] == [seeded["always"]]
+    assert [s["id"] for s in applicable["subscribed_rulebooks"]] == [seeded["other"]]
+    # The record, written last, says why.
+    async with async_session() as s:
+        project = await s.get(Project, pid)
+    assert inception_svc.is_decided(project)
+    assert project.inception["via"] == "mcp" and project.inception["decided_by"] == owner
+    assert project.inception["choices"]["exclude_always_on_rulebooks"] == [seeded["always"]]
+    # Re-deciding with seed again mints nothing twice; include reverses the exclusion.
+    again = await inception_svc.decide(owner, pid, via="ui", choices={"seed_systems": True})
+    assert again["effects"]["systems_seeded"] == []
+    assert len(await systems_svc.list_systems(owner, pid)) == len(systems_svc.STANDARD_SYSTEMS)
+    await rulebooks_svc.include_always_on_rulebook_for_project(pid, seeded["always"], owner)
+    assert [r.title for r in await rulebooks_svc.list_always_on_rules(owner, project_id=pid)] == ["dev is home"]
+
+
+@pytest.mark.integration
+async def test_a_bad_decision_applies_nothing(seeded):
+    owner, pid = seeded["owner"], seeded["pid"]
+    # Excluding a rulebook that is not always-on is refused BEFORE any effect.
+    with pytest.raises(ValueError, match="not always-on"):
+        await inception_svc.decide(owner, pid, via="mcp", choices={
+            "exclude_always_on_rulebooks": [seeded["other"]], "seed_systems": True,
+        })
+    assert await systems_svc.list_systems(owner, pid) == []
+    with pytest.raises(ValueError, match="not found"):
+        await inception_svc.decide(owner, pid, via="mcp", choices={"subscribe_rulebooks": [999999]})
+    with pytest.raises(ValueError, match="legacy"):
+        await inception_svc.decide(owner, pid, via="legacy", choices={})
+    async with async_session() as s:
+        project = await s.get(Project, pid)
+    assert not inception_svc.is_decided(project)
+    # An outsider cannot decide someone else's project.
+    async with async_session() as s:
+        other = await ensure_user(s, "inception_other")
+        other_id = other.id
+        await s.commit()
+    with pytest.raises(ValueError, match="not found"):
+        await inception_svc.decide(other_id, pid, via="mcp", choices={})

tests/test_integration_shape_classify.py

@@ -15,6 +15,7 @@ from scribe.models.project import Project
 from scribe.models.user import User
 from scribe.services.shape_ledger import (
     classify_shapes,
+    classify_shapes_where,
     list_project_shapes,
     snippet_consumers,
     sync_repo_shapes,
@@ -128,6 +129,126 @@ async def test_classification_is_write_gated_and_listing_read_gated(seeded):
     assert await list_project_shapes(other, pid) == ([], 0)
 
 
+@pytest.mark.integration
+async def test_rule_form_sweeps_unclassified_rows_only_and_applies_whole(seeded):
+    """#2868: one judgment over a directory + glob; judged rows are left
+    alone unless include_judged; the same gates as the row form."""
+    owner, other, pid, sid = seeded["owner"], seeded["other"], seeded["pid"], seeded["snippet"]
+    await classify_shapes(owner, pid, [
+        {"path": "src/app.py", "symbol": "Config", "status": "exempt", "reason": "settings holder"},
+    ])
+    out = await classify_shapes_where(
+        owner, pid, path="src", status="instance", snippet_id=sid, via="audit",
+    )
+    # make_app + helper swept; Config (already judged) untouched; css not under src/.
+    assert out["classified"] == 2
+    assert out["sample"] == ["src/app.py::make_app", "src/util.py::helper"]
+    rows, _ = await list_project_shapes(owner, pid)
+    by_symbol = {r.symbol: r for r in rows}
+    assert by_symbol["make_app"].status == "instance" and by_symbol["make_app"].classified_by == "audit"
+    assert by_symbol["Config"].status == "exempt" and by_symbol["Config"].reason == "settings holder"
+    assert by_symbol["btn"].status == "unclassified"
+    # Glob + kind narrow; include_judged re-judges.
+    out = await classify_shapes_where(
+        owner, pid, path="web", status="exempt", pattern="btn*", kind="css",
+        reason="one toolbar button", include_judged=True,
+    )
+    assert out["classified"] == 1
+    out = await classify_shapes_where(
+        owner, pid, path="src", status="unclassified", include_judged=True,
+    )
+    assert out["classified"] == 3   # withdrawal sweeps judged rows when asked
+    # Gates: reason for exempt, snippet for instance, write access, a path.
+    with pytest.raises(ValueError):
+        await classify_shapes_where(owner, pid, path="src", status="exempt")
+    with pytest.raises(ValueError):
+        await classify_shapes_where(owner, pid, path="src", status="instance")
+    with pytest.raises(ValueError):
+        await classify_shapes_where(owner, pid, path="", status="exempt", reason="x")
+    with pytest.raises(ValueError):
+        await classify_shapes_where(other, pid, path="src", status="exempt", reason="x")
+
+
+@pytest.mark.integration
+async def test_sync_stamps_scoped_rows_and_unstamps_when_they_become_reachable(seeded):
+    """#2869: by-construction one-offs arrive `scoped` (mechanical), count as
+    accounted, are reached by the sweep's default, and go back to the todo
+    if a later tree makes them ordinary. A judgment overrides the stamp."""
+    from scribe.services.coverage import ArchiveShape
+    owner, pid, sid = seeded["owner"], seeded["pid"], seeded["snippet"]
+    scoped_shapes = [
+        ArchiveShape("web/Card.vue", "css", "card", ".card {", "s1", ".card { x: 1 }", True),
+        ArchiveShape("web/Card.vue", "sym", "load", "function load() {", "s2", "function load() {}", True),
+        ArchiveShape("src/util.py", "sym", "helper", "def helper():", "s3", "def helper(): pass", False),
+    ]
+    await sync_repo_shapes(pid, REPO, scoped_shapes, seen_marker="main")
+    rows, _ = await list_project_shapes(owner, pid, path="web/Card.vue")
+    assert {r.status for r in rows} == {"scoped"}
+    assert all(r.classified_by == "mechanical" and "by construction" in (r.reason or "") for r in rows)
+    # The human todo excludes them; the sweep's default still reaches them.
+    assert (await list_project_shapes(owner, pid, status="unclassified", path="web/Card.vue"))[1] == 0
+    out = await classify_shapes_where(
+        owner, pid, path="web/Card.vue", status="instance", snippet_id=sid, kind="css",
+    )
+    assert out["classified"] == 1
+    # Re-synced as ordinary: the stamped sym returns to the todo; the
+    # judged css keeps its judgment.
+    plain = [ArchiveShape(s.path, s.kind, s.name, s.signature, s.body_sha, s.body, False) for s in scoped_shapes]
+    await sync_repo_shapes(pid, REPO, plain, seen_marker="main")
+    rows, _ = await list_project_shapes(owner, pid, path="web/Card.vue")
+    by_symbol = {r.symbol: r for r in rows}
+    assert by_symbol["load"].status == "unclassified" and by_symbol["load"].classified_by is None
+    assert by_symbol["card"].status == "instance" and by_symbol["card"].snippet_id == sid
+
+
+@pytest.mark.integration
+async def test_uses_edges_are_the_consumer_map(seeded):
+    """#2870: a shape keeps ONE snippet_id (what it is) and any number of
+    uses edges (what it calls); the snippet's consumer map lists them,
+    list_shapes(uses=N) finds them, and a sweep can write them."""
+    from scribe.services import snippets as snippets_svc
+    owner, pid, sid = seeded["owner"], seeded["pid"], seeded["snippet"]
+    helper = await snippets_svc.create_snippet(
+        owner, name="cls_hash_helper", code="def hash_token(raw):\n    return raw\n",
+        language="python", repo="Widget", path="src/hash.py", symbol="hash_token",
+        project_id=pid,
+    )
+    hid = int(helper.id)
+    out = await classify_shapes(owner, pid, [
+        {"path": "src/app.py", "symbol": "make_app", "status": "instance",
+         "snippet_id": sid, "uses": [hid]},
+    ], via="audit")
+    assert out["classified"] == 1
+    rows, total = await list_project_shapes(owner, pid, uses=hid)
+    assert total == 1 and rows[0].symbol == "make_app" and rows[0].snippet_id == sid
+    consumers = await snippet_consumers(owner, hid)
+    assert consumers["instances"] == [] and len(consumers["uses"]) == 1
+    assert consumers["uses"][0]["symbol"] == "make_app" and consumers["uses"][0]["basis"] == "audit"
+    # A sweep writes uses too; an unknown snippet in uses applies nothing.
+    out = await classify_shapes_where(
+        owner, pid, path="src/util.py", status="exempt", reason="local", uses=[hid],
+    )
+    assert out["classified"] == 1
+    assert (await list_project_shapes(owner, pid, uses=hid))[1] == 2
+    # The proposer writes uses edges for JUDGED rows too: Config (exempt)
+    # names hash_token in its body → an edge, no proposal.
+    from scribe.services.shape_ledger import propose_for_repo
+    await classify_shapes(owner, pid, [
+        {"path": "src/app.py", "symbol": "Config", "status": "exempt", "reason": "settings"},
+    ])
+    defs = _defs(("src/app.py", "sym", "Config", "class Config:", "class Config:\n    token = hash_token(raw)\n"))
+    with _quiet_semantic():
+        await propose_for_repo(owner, pid, REPO, defs)
+    rows, total = await list_project_shapes(owner, pid, uses=hid)
+    assert total == 3 and {r.symbol for r in rows} >= {"Config"}
+    cfg = next(r for r in rows if r.symbol == "Config")
+    assert cfg.status == "exempt" and cfg.proposal is None
+    with pytest.raises(ValueError):
+        await classify_shapes(owner, pid, [
+            {"path": "src/app.py", "symbol": "Config", "status": "exempt", "reason": "x", "uses": [999999]},
+        ])
+
+
 @pytest.mark.integration
 async def test_list_filters_compose(seeded):
     owner, pid, sid = seeded["owner"], seeded["pid"], seeded["snippet"]
@@ -170,7 +291,7 @@ async def test_get_snippet_carries_the_structured_consumer_map(seeded):
     # The map is caller-scoped: an outsider asking the service directly gets
     # silence, not another project's file layout.
     consumers = await snippet_consumers(seeded["other"], sid)
-    assert consumers == {"instances": [], "variants": []}
+    assert consumers == {"instances": [], "variants": [], "uses": []}
 
 
 @pytest.mark.integration
@@ -458,9 +579,14 @@ async def test_derive_groups_land_on_rows_and_in_the_summary(seeded):
 
     summary = proposal_summary(await live_rows(pid))
     assert summary["proposed"] == 1
-    assert [g["group"] for g in summary["derive_groups"]][0] == "name:css:card"
-    assert summary["derive_groups"][0]["label"] == ".card"
-    assert summary["derive_groups"][0]["size"] == 3
+    # #2872: the body-identical group (a real copy) outranks the bigger name
+    # group (usually convention), even at size 2 vs 3.
+    order = [g["group"] for g in summary["derive_groups"]]
+    assert order[0].startswith("dup:") and order[1] == "name:css:card"
+    assert summary["derive_groups"][0]["files"] == 2
+    assert summary["derive_groups"][0]["label"] == "slug (identical body)"
+    assert summary["derive_groups"][1]["label"] == ".card"
+    assert summary["derive_groups"][0]["size"] == 2 and summary["derive_groups"][1]["size"] == 3
 
     # One of the css copies gets judged → the group shrinks on the next pass.
     await classify_shapes(owner, pid, [
@@ -489,7 +615,20 @@ async def test_a_second_confirm_dialog_is_detected_and_named(seeded):
         write_time_divergence,
     )
 
-    owner, pid, sid = seeded["owner"], seeded["pid"], seeded["snippet"]
+    from scribe.services import snippets as snippets_svc
+
+    owner, pid = seeded["owner"], seeded["pid"]
+    # The confirm helper is TS canon: since #2871 a sym basis only proposes
+    # within the shape's language family, so the fixture's Python snippet
+    # says nothing about these Vue bodies — the canon must be one of theirs.
+    canon = await snippets_svc.create_snippet(
+        owner, name="cls_confirm_factory",
+        code="export async function factory(): Promise<boolean> {\n  return true;\n}\n",
+        language="typescript", repo="Widget",
+        path="frontend/src/composables/useConfirm.ts", symbol="factory",
+        project_id=pid,
+    )
+    sid = int(canon.id)
     comp = "frontend/src/components"
     base = _defs(
         *[(f"{comp}/{n}.vue", "sym", f"on{n}", f"async function on{n}() {{",

tests/test_mcp_tool_projects.py

@@ -391,3 +391,81 @@ def test_enter_project_registered_in_register():
 
     register(mcp)
     assert "enter_project" in mcp.names
+
+
+# --- milestone 297: the inception doors ---------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_create_project_without_inception_args_stays_undecided():
+    p = fake_project(id=5, title="P", inception=None)
+    with patch("scribe.mcp.tools.projects.projects_svc.create_project", AsyncMock(return_value=p)), \
+         patch("scribe.mcp.tools.projects.inception_svc.decide", AsyncMock()) as decide:
+        out = await create_project(title="P")
+    decide.assert_not_awaited()
+    assert "inception_hint" in out and "inception_effects" not in out
+
+
+@pytest.mark.asyncio
+async def test_create_project_with_inception_args_decides_via_mcp():
+    p = fake_project(id=5, title="P", inception=None)
+    decided = {"inception": {"via": "mcp", "choices": {}}, "effects": {"systems_seeded": []}}
+    with patch("scribe.mcp.tools.projects.projects_svc.create_project", AsyncMock(return_value=p)), \
+         patch("scribe.mcp.tools.projects.inception_svc.decide", AsyncMock(return_value=decided)) as decide:
+        out = await create_project(title="P", exclude_always_on_rulebooks=[1], design_system_id=-1, seed_systems=True)
+    kw = decide.await_args.kwargs
+    assert decide.await_args.args[1] == 5 and kw["via"] == "mcp"
+    assert kw["choices"] == {"exclude_always_on_rulebooks": [1], "subscribe_rulebooks": [],
+                             "design_system_id": None, "seed_systems": True}
+    assert out["inception"]["via"] == "mcp" and "inception_effects" in out
+
+
+@pytest.mark.asyncio
+async def test_decide_project_inception_tool_records_an_inherit_all_decision_when_given_nothing():
+    from scribe.mcp.tools.projects import decide_project_inception
+    decided = {"inception": {"via": "mcp"}, "effects": {}}
+    with patch("scribe.mcp.tools.projects.inception_svc.decide", AsyncMock(return_value=decided)) as decide:
+        out = await decide_project_inception(project_id=5)
+    assert decide.await_args.kwargs["choices"] == {}
+    assert out["project_id"] == 5 and out["inception"]["via"] == "mcp"
+
+
+@pytest.mark.asyncio
+async def test_enter_project_carries_the_inception_ask_only_for_an_undecided_own_project():
+    applicable = {"rules": [], "project_rules": [], "truncated": False,
+                  "subscribed_rulebooks": [], "excluded_always_on": []}
+    ask = {"defaults": {}, "ask": "decide", "call": "decide_project_inception(...)"}
+
+    async def run(project):
+        with patch("scribe.mcp.tools.projects.projects_svc.get_project", AsyncMock(return_value=project)), \
+             patch("scribe.mcp.tools.projects.rulebooks_svc.get_applicable_rules", AsyncMock(return_value=applicable)), \
+             patch("scribe.mcp.tools.projects.milestones_svc.get_project_milestone_summary", AsyncMock(return_value=[])), \
+             patch("scribe.mcp.tools.projects.notes_svc.list_notes", AsyncMock(side_effect=[([], 0), ([], 0)])), \
+             patch("scribe.mcp.tools.projects.systems_svc.list_systems", AsyncMock(return_value=[])), \
+             patch("scribe.mcp.tools.projects.systems_tools.bootstrap_systems_ask", AsyncMock(return_value=None)), \
+             patch("scribe.mcp.tools.projects.inception_svc.inception_ask", AsyncMock(return_value=ask)) as asked:
+            return await enter_project(project_id=5), asked
+
+    # Own + undecided → the ask rides along.
+    out, asked = await run(fake_project(id=5, title="P", user_id=7, inception=None))
+    assert out["inception"] == ask and asked.await_count == 1
+    # Decided → absent, and the ask is not even built.
+    out, asked = await run(fake_project(id=5, title="P", user_id=7, inception={"via": "legacy"}))
+    assert "inception" not in out and asked.await_count == 0
+    # Someone else's (shared) project, undecided → not this caller's to decide.
+    out, asked = await run(fake_project(id=5, title="P", user_id=8, inception=None))
+    assert "inception" not in out and asked.await_count == 0
+
+
+def test_inception_routes_and_tool_are_registered():
+    from scribe.app import create_app
+    from scribe.mcp.server import build_mcp_server
+    rules = {r.rule for r in create_app().url_map.iter_rules()}
+    assert "/api/projects/<int:project_id>/inception" in rules
+    assert "/api/projects/<int:project_id>/inception/defaults" in rules
+    mcp = build_mcp_server()
+    assert mcp._tool_manager.get_tool("decide_project_inception") is not None
+    tool = mcp._tool_manager.get_tool("create_project")
+    for name in ("exclude_always_on_rulebooks", "subscribe_rulebooks", "design_system_id", "seed_systems"):
+        assert name in tool.parameters.get("properties", {}), name
+

tests/test_mcp_tool_rulebooks.py

@@ -169,12 +169,15 @@ def test_register_attaches_all_sixteen_tools():
     mcp = FakeMCP()
 
     register(mcp)
-    assert len(mcp.names) == 22
+    assert len(mcp.names) == 24   # +exclude/include_always_on_rulebook (milestone 297)
     # spot-check a few names
     assert "list_rulebooks" in mcp.names
     assert "create_rule" in mcp.names
     assert "subscribe_project_to_rulebook" in mcp.names
     assert "list_always_on_rules" in mcp.names
+    # milestone 297: a project's opt-out of a whole always-on rulebook
+    assert "exclude_always_on_rulebook" in mcp.names
+    assert "include_always_on_rulebook" in mcp.names
     assert "create_project_rule" in mcp.names
     assert "suppress_rule_for_project" in mcp.names
     assert "unsuppress_rule_for_project" in mcp.names

tests/test_pattern_coverage.py

@@ -168,6 +168,13 @@ def test_coverage_line_is_evidence_carrying_and_labeled_estimate():
     assert "internal/api, web/src/components" in line
 
 
+def test_bind_repo_tool_takes_a_ref():
+    """#2873: the binding names the branch the ledger follows."""
+    from scribe.mcp.server import build_mcp_server
+    tool = build_mcp_server()._tool_manager.get_tool("bind_repo")
+    assert "ref" in tool.parameters.get("properties", {})
+
+
 def test_coverage_routes_are_registered():
     from scribe.app import create_app
 
@@ -188,7 +195,8 @@ def _forge(tar_bytes: bytes):
         path = request.url.path
         if path == "/api/v1/repos/alice/widget":
             return httpx.Response(200, json={"default_branch": "main"})
-        if path == "/api/v1/repos/alice/widget/archive/main.tar.gz":
+        if path in ("/api/v1/repos/alice/widget/archive/main.tar.gz",
+                    "/api/v1/repos/alice/widget/archive/dev.tar.gz"):
             return httpx.Response(200, content=tar_bytes)
         return httpx.Response(404, json={"message": "not found"})
 
@@ -258,7 +266,7 @@ async def test_coverage_measures_the_tree_exactly_and_caches(seeded):
     assert coverage["accounted"] == 2
     assert coverage["unclassified"] == 2
     assert coverage["counts"] == {
-        "canonical": 2, "instance": 0, "variant": 0, "exempt": 0,
+        "canonical": 2, "instance": 0, "variant": 0, "exempt": 0, "scoped": 0,
     }
     assert coverage["estimate"] is True
     assert coverage["repos"] == [{
@@ -468,6 +476,18 @@ def test_extract_definitions_fingerprints_each_block():
     # And the identity view is unchanged for the hook mirror.
     from scribe.services.coverage import extract_shapes
     assert extract_shapes(text) == [(d.kind, d.name) for d in extract_definitions(text)]
+    # A CSS rule's fingerprint is its declarations (#2872): the same body
+    # under another selector is the same shape to the derive grouping.
+    css = ".closed-msg {\n  text-align: center;\n  padding: 0.5rem 0;\n}\n.error-block {\n  text-align: center;\n  padding: 0.5rem 0;\n}\n.other {\n  text-align: left;\n}\n"
+    d = {x.name: x for x in extract_definitions(css)}
+    assert d["closed-msg"].body_sha == d["error-block"].body_sha != d["other"].body_sha
+    # One-line rules hash their own declarations — never the empty string
+    # (first deploy grouped 68 unrelated one-liners as one copy).
+    one = ".a { color: red; }\n\n.b { color: red; }\n\n.c { color: blue; }\n\n.d {\n  color: red;\n}\n"
+    e = {x.name: x for x in extract_definitions(one)}
+    import hashlib
+    assert e["a"].body_sha == e["b"].body_sha != e["c"].body_sha
+    assert e["a"].body_sha != hashlib.sha1(b"").hexdigest()[:16]
 
 
 def test_coverage_line_names_the_proposers_standing():
@@ -484,6 +504,12 @@ def test_coverage_line_names_the_proposers_standing():
     assert "; 90 unclassified (40 proposed, 2 derive groups), largest: src" in line
     line = coverage_line({**base, "proposed": 0, "derive_groups": [{"group": "a"}]})
     assert "(1 derive group)" in line
+    # #2874: the next action on the line — biggest canon queue, widest copy.
+    line = coverage_line({
+        **base, "proposed": 40, "top_canon": {"snippet_id": 2844, "count": 78},
+        "derive_groups": [{"group": "dup:abc", "label": "closed-msg (identical body)", "files": 3}],
+    })
+    assert "top canon #2844 ×78" in line and "top copy closed-msg (identical body) ×3 files" in line
 
 
 def test_coverage_line_names_divergence_and_recheck():
@@ -500,3 +526,52 @@ def test_coverage_line_names_divergence_and_recheck():
     assert line.endswith("; 1 judged shape changed since judged — recheck")
     assert "DIVERGENT" not in coverage_line(base)
     assert "recheck" not in coverage_line(base)
+
+
+def test_scoped_definitions_are_vue_script_setup_and_scoped_style_only():
+    """#2869: one-offs by construction — every sym in a .vue and every css
+    rule inside <style scoped>; an unscoped <style> block and non-.vue files
+    stay ordinary."""
+    from scribe.services.coverage import extract_definitions, scoped_definitions
+    vue = (
+        "<script setup lang=\"ts\">\n"
+        "function load() {\n  return 1;\n}\n"
+        "const save = async () => {\n  return 2;\n};\n"
+        "</script>\n\n"
+        "<template><div class=\"card\"/></template>\n\n"
+        "<style scoped>\n.card {\n  padding: 1rem;\n}\n.title {\n  margin: 0;\n}\n</style>\n"
+        "<style>\n.global-toast {\n  color: red;\n}\n</style>\n"
+    )
+    defs = extract_definitions(vue)
+    names = {(d.kind, d.name) for d in defs}
+    assert {("sym", "load"), ("sym", "save"), ("css", "card"), ("css", "title"), ("css", "global-toast")} <= names
+    scoped = scoped_definitions("frontend/src/views/A.vue", vue, defs)
+    assert scoped == {("sym", "load"), ("sym", "save"), ("css", "card"), ("css", "title")}
+    # Definitions know their line, which is what the scoped-style range uses.
+    assert next(d for d in defs if d.name == "card").line > next(d for d in defs if d.name == "save").line
+    # Not a .vue: nothing is scoped, whatever it contains.
+    assert scoped_definitions("frontend/src/assets/components.css", ".card {\n  x: 1;\n}\n",
+                              extract_definitions(".card {\n  x: 1;\n}\n")) == set()
+    assert scoped_definitions("src/a.py", "def load():\n    pass\n", extract_definitions("def load():\n    pass\n")) == set()
+
+
+@pytest.mark.integration
+async def test_binding_ref_is_the_branch_the_ledger_follows(seeded):
+    """#2873: a binding that names a ref is read at that ref (not the forge's
+    default branch); "" clears it; None on a re-bind leaves it standing."""
+    from scribe.services.coverage import compute_coverage
+    from scribe.services.repo_bindings import bindings_for_project, set_binding
+    uid, pid = seeded["uid"], seeded["pid"]
+    b = await set_binding(uid, "https://git.example.com/alice/widget.git", pid, "dev")
+    assert b.ref == "dev"
+    coverage = await compute_coverage(uid, pid, selector=_selector(_tarball(TREE)))
+    assert coverage["repos"][0]["ref"] == "dev"
+    # A re-bind without a ref keeps it; "" clears it back to the default branch.
+    b = await set_binding(uid, "https://git.example.com/alice/widget.git", pid)
+    assert b.ref == "dev"
+    b = await set_binding(uid, "https://git.example.com/alice/widget.git", pid, "")
+    assert b.ref is None
+    assert [x.ref for x in await bindings_for_project(uid, pid)] == [None]
+    coverage = await compute_coverage(uid, pid, selector=_selector(_tarball(TREE)))
+    assert coverage["repos"][0]["ref"] == "main"
+

tests/test_services_backup.py

@@ -18,7 +18,7 @@ def test_backup_version_is_v8():
     point of the test — a payload section added without moving the version
     produces backups that are structurally different and indistinguishable
     by inspection."""
-    assert backup.BACKUP_VERSION == 8
+    assert backup.BACKUP_VERSION == 10
 
 
 def test_not_included_lists_the_known_gaps():
@@ -115,7 +115,8 @@ async def test_export_full_backup_contains_every_declared_section():
                 "topic_suppressions",
                 "systems", "record_systems", "design_systems",
                 "design_tokens", "note_usage_events", "repo_bindings",
-                "note_supersessions", "code_shapes", "code_shape_events"):
+                "note_supersessions", "code_shapes", "code_shape_events",
+                "code_shape_uses", "rulebook_exclusions"):
         assert key in out, f"missing export section: {key}"
         assert out[key] == []
 

tests/test_services_plugin_context.py

@@ -4,6 +4,15 @@ import pytest
 from tests.helpers import fake_note
 
 
+@pytest.fixture(autouse=True)
+def _no_exclusions():
+    """build_session_context asks for the bound project's always-on
+    exclusions (milestone 297); these tests script the rules only."""
+    with patch("scribe.services.plugin_context.rulebooks_svc.excluded_always_on_rulebooks",
+               AsyncMock(return_value=[])):
+        yield
+
+
 pytestmark = pytest.mark.usefixtures("_no_supersession")
 
 

tests/test_services_rulebooks.py

@@ -8,6 +8,15 @@ import pytest
 from tests.helpers import fake_rule, fake_rulebook, fake_topic, make_mock_session
 
 
+@pytest.fixture(autouse=True)
+def _no_exclusions():
+    """get_applicable_rules asks for the project's always-on exclusions
+    (milestone 297) through its own session; these mocked-session tests
+    script the rule queries only, so the exclusions lookup is stubbed empty."""
+    with patch("scribe.services.rulebooks.excluded_always_on_rulebooks", AsyncMock(return_value=[])):
+        yield
+
+
 @pytest.mark.asyncio
 async def test_create_rulebook_stores_to_db():
     mock_session = make_mock_session()

tests/test_shape_ledger.py

@@ -30,7 +30,7 @@ def test_the_todo_state_is_the_default():
     assert CodeShape.__table__.c.status.default.arg == "unclassified"
     assert "unclassified" in SHAPE_STATUSES
     assert set(SHAPE_STATUSES) == {
-        "canonical", "instance", "variant", "exempt", "unclassified",
+        "canonical", "instance", "variant", "exempt", "scoped", "unclassified",
     }
     assert set(SHAPE_CLASSIFIERS) == {
         "agent", "audit", "hook", "mechanical", "import",
@@ -248,6 +248,49 @@ def test_match_canon_orders_bases_strongest_first_and_respects_kind():
     assert match_canon("sym", "x.py", "unrelated", "def unrelated(a, b, c, d, e):", "return 1", canons) is None
 
 
+def test_match_canon_gates_sym_bases_by_language_family():
+    """A Python canon says nothing about a Vue body (and vice versa): the
+    2026-08 audit's worst proposals were `register` (MCP tool module, python)
+    offered for every auth view's handleSubmit that calls authStore.register()
+    and for a TS store's own `register`. Unknown language on either side →
+    no gate (the canons recorded without a language keep proposing)."""
+    from scribe.services.shape_ledger import Canon, _norm_text, match_canon, same_family
+    py_register = Canon(46, "sym", "register", (("src/scribe/mcp/tools/notes.py", "register"),),
+                        "def register(mcp) -> None:", _norm_text("def register(mcp) -> None: ..."), 2, "python")
+    ts_helper = Canon(53, "sym", "apiErrorMessage", (("frontend/src/api/client.ts", "apiErrorMessage"),),
+                      "export function apiErrorMessage(e: unknown, fallback: string): string {",
+                      _norm_text("export function apiErrorMessage(e, fallback) { return fallback }"), 2, "typescript")
+    canons = [py_register, ts_helper]
+    vue_body = "async function handleSubmit() {\n  await authStore.register(username.value);\n  error.value = apiErrorMessage(e, 'x');\n}"
+    # The Vue handler references the TS helper, never the Python canon.
+    assert match_canon("sym", "frontend/src/views/RegisterView.vue", "handleSubmit",
+                       "async function handleSubmit() {", vue_body, canons) == (53, "reference", 0.9)
+    # A TS store's own `register` is not a second definition of the Python one.
+    assert match_canon("sym", "frontend/src/stores/auth.ts", "register",
+                       "async function register(u: string) {", "return apiPost('/api/auth/register', {u})",
+                       [py_register]) is None
+    # Same family still proposes by symbol; unknown language still proposes.
+    assert match_canon("sym", "src/scribe/mcp/tools/other.py", "register",
+                       "def register(mcp) -> None:", "pass", [py_register]) == (46, "symbol", 1.0)
+    unknown = py_register._replace(language="")
+    assert match_canon("sym", "frontend/src/stores/auth.ts", "register",
+                       "async function register(u: string) {", "", [unknown]) == (46, "symbol", 1.0)
+    assert same_family("a.py", "python") and same_family("a.vue", "typescript")
+    assert same_family("a.py", "") and same_family("", "python")
+    assert not same_family("a.py", "vue")
+
+
+def test_match_canon_reference_skips_generic_verbs():
+    """A bare mention of `load`/`save`/`register` is not a call site of THIS
+    canon; the symbol basis still catches a second definition of the name."""
+    from scribe.services.shape_ledger import Canon, _norm_text, match_canon
+    loader = Canon(70, "sym", "load", (("frontend/src/components/A.vue", "load"),),
+                   "async function load() {", _norm_text("async function load() { await fetch() }"), 2, "vue")
+    body = "async function refresh() {\n  await load();\n}"
+    assert match_canon("sym", "frontend/src/components/B.vue", "refresh", "async function refresh() {", body, [loader]) is None
+    assert match_canon("sym", "frontend/src/components/B.vue", "load", "async function load() {", "", [loader]) == (70, "symbol", 1.0)
+
+
 def test_match_canon_symbol_beats_everything_including_css_copies():
     """The previous test's css `btn-primary`-elsewhere case, stated plainly:
     a second definition of the canon's own name is the symbol basis."""
@@ -274,6 +317,32 @@ def test_derive_groups_copy_before_name_with_floors():
     assert ("i.py", "sym", "one") not in g
 
 
+def test_proposal_summary_ranks_body_identical_groups_first_and_sees_scoped_rows():
+    """#2872: dup groups (the real copies) outrank name groups (usually
+    convention), wider spread first; #2869: scoped rows are in the readout."""
+    from scribe.models.code_shape import CodeShape
+    from scribe.services.shape_ledger import proposal_summary
+
+    def row(path, symbol, group, kind="css", status="scoped"):
+        return CodeShape(project_id=2, repo_key="r", path=path, symbol=symbol, kind=kind,
+                         status=status, proposal_basis="derive", proposal_group=group)
+    rows = [
+        # a name group of 6 across 6 files
+        *[row(f"v/{i}.vue", "status-badge", "name:css:status-badge") for i in range(6)],
+        # a dup group of 3 across 3 files (different selector names, one body)
+        row("v/Login.vue", "closed-msg", "dup:abc"), row("v/Reset.vue", "error-block", "dup:abc"),
+        row("v/Forgot.vue", "success-msg", "dup:abc"),
+        # a dup group of 2 in ONE file — a copy, but not across files
+        row("v/A.vue", "x", "dup:def"), row("v/A.vue", "y", "dup:def"),
+        # judged rows never count
+        row("v/J.vue", "closed-msg", "dup:abc", status="exempt"),
+    ]
+    out = proposal_summary(rows)
+    assert [g["group"] for g in out["derive_groups"]] == ["dup:abc", "dup:def", "name:css:status-badge"]
+    assert out["derive_groups"][0]["files"] == 3 and out["derive_groups"][0]["size"] == 3
+    assert out["derive_groups"][0]["label"] == "closed-msg (identical body)"
+
+
 def test_confirm_requires_a_named_scope():
     import asyncio
 
@@ -291,6 +360,99 @@ def test_proposer_tools_are_mounted():
     assert mcp._tool_manager.get_tool("confirm_shape_proposals") is not None
     tool = mcp._tool_manager.get_tool("list_shapes")
     assert "proposal" in tool.parameters.get("properties", {})
+    # #2868: the audit surfaces — compact pages and the sweep form.
+    assert "compact" in tool.parameters.get("properties", {})
+    rule = mcp._tool_manager.get_tool("classify_shapes_by_rule")
+    assert rule is not None
+    for name in ("path", "status", "pattern", "kind", "snippet_id", "reason", "include_judged"):
+        assert name in rule.parameters.get("properties", {}), name
+
+
+# --- #2868: the bulk surfaces (pure) -----------------------------------------
+
+
+def test_compact_row_carries_identity_standing_and_the_proposers_word_only():
+    """A 500-row compact page must fit the tool budget: no commits, shas or
+    timestamps; optional fields only when set."""
+    from scribe.models.code_shape import CodeShape
+    row = CodeShape(project_id=2, repo_key="r", path="src/a.py", symbol="f", kind="sym",
+                    status="unclassified", signature="def f(x):", body_sha="abc",
+                    first_seen_commit="c1", last_seen_commit="c2")
+    assert row.to_compact() == {
+        "path": "src/a.py", "symbol": "f", "kind": "sym",
+        "status": "unclassified", "signature": "def f(x):",
+    }
+    row.status, row.snippet_id, row.classified_by = "instance", 9, "audit"
+    row.proposed_snippet_id, row.proposal_basis, row.proposal_score = 9, "symbol", 1.0
+    compact = row.to_compact()
+    assert compact["snippet_id"] == 9 and compact["by"] == "audit"
+    assert compact["proposal"]["basis"] == "symbol"
+    for noisy in ("first_seen_commit", "last_seen_commit", "body_sha", "created_at", "classified_at"):
+        assert noisy not in compact
+
+
+def test_uses_edges_table_and_validation():
+    """#2870: consumption is its own relation — a table that cascades with
+    both ends, and `uses` on a classification must be a list of ids."""
+    from scribe.models import Base
+    from scribe.models.code_shape import USE_BASES, CodeShapeUse
+    from scribe.services.shape_ledger import validate_classifications
+    assert "code_shape_uses" in Base.metadata.tables
+    cols = CodeShapeUse.__table__.c
+    assert next(iter(cols.shape_id.foreign_keys)).ondelete == "CASCADE"
+    assert next(iter(cols.snippet_id.foreign_keys)).ondelete == "CASCADE"
+    assert set(USE_BASES) == {"reference", "hook", "agent", "audit", "import"}
+    ok = [{"path": "a.py", "symbol": "f", "status": "instance", "snippet_id": 9, "uses": [3, 4]}]
+    assert validate_classifications(ok) is None
+    bad = [{"path": "a.py", "symbol": "f", "status": "instance", "snippet_id": 9, "uses": "3"}]
+    assert "uses must be a list" in validate_classifications(bad)
+
+
+def test_reference_canons_names_every_used_canon_not_just_the_best():
+    from scribe.services.shape_ledger import Canon, _norm_text, reference_canons
+    a = Canon(1, "sym", "hash_token", (("src/x.py", "hash_token"),), "def hash_token(raw):", _norm_text("x"), 2, "python")
+    b = Canon(2, "sym", "rules_payload", (("src/y.py", "rules_payload"),), "def rules_payload(r):", _norm_text("y"), 2, "python")
+    ts = Canon(3, "sym", "fmtDate", (("f/d.ts", "fmtDate"),), "export function fmtDate(iso: string): string {", _norm_text("z"), 2, "typescript")
+    body = "def create_invitation(email):\n    h = hash_token(raw)\n    return rules_payload(h)\n"
+    assert reference_canons("sym", "src/scribe/services/auth.py", "create_invitation", body, [a, b, ts]) == [1, 2]
+    # the shape's own name and the other language family are never "uses"
+    assert reference_canons("sym", "src/x.py", "hash_token", body, [a]) == []
+    assert reference_canons("sym", "f/v.vue", "show", "fmtDate(x); hash_token(y)", [a, ts]) == [3]
+
+
+def test_reason_codes_are_a_fixed_catalogue_and_validated():
+    """#2874: an optional index beside the prose reason; unknown codes are a
+    structural error (the batch applies nothing)."""
+    from scribe.models.code_shape import REASON_CODES
+    from scribe.services.shape_ledger import validate_classifications
+    assert set(REASON_CODES) == {
+        "scoped-css", "one-off-handler", "test-helper", "convention-plumbing",
+        "pure-helper", "generated", "script", "typed-record",
+    }
+    assert "reason_code" in CodeShape.__table__.c
+    ok = [{"path": "a.py", "symbol": "f", "status": "exempt", "reason": "x", "reason_code": "pure-helper"}]
+    assert validate_classifications(ok) is None
+    bad = [{"path": "a.py", "symbol": "f", "status": "exempt", "reason": "x", "reason_code": "nope"}]
+    assert "unknown reason_code" in validate_classifications(bad)
+
+
+def test_rule_matches_is_directory_glob_and_kind_aware():
+    from scribe.models.code_shape import CodeShape
+    from scribe.services.shape_ledger import rule_matches
+
+    def row(path, symbol, kind="sym"):
+        return CodeShape(project_id=2, repo_key="r", path=path, symbol=symbol, kind=kind, status="unclassified")
+
+    r = row("frontend/src/views/LoginView.vue", "auth-card", "css")
+    assert rule_matches(r, path="frontend/src/views", pattern="", kind="")
+    assert rule_matches(r, path="frontend/src/views", pattern="auth-*", kind="css")
+    assert not rule_matches(r, path="frontend/src/views", pattern="auth-*", kind="sym")
+    assert not rule_matches(r, path="frontend/src/view", pattern="", kind="")   # directory, not prefix
+    assert rule_matches(r, path="frontend/src/views/LoginView.vue", pattern="", kind="")
+    # CSS symbols compare without the leading dot, like everywhere else.
+    assert rule_matches(row("w/a.css", ".btn-primary", "css"), path="w", pattern="btn-*", kind="css")
+    assert rule_matches(row("src/scribe/services/backup.py", "_note_rows"), path="src/scribe/services", pattern="_*_rows", kind="")
+    assert not rule_matches(row("src/scribe/services/backup.py", "export_full_backup"), path="src/scribe/services", pattern="_*_rows", kind="")
 
 
 # --- step 7: the divergence readout (pure) ----------------------------------

tests/test_snippet_location_filter.py

@@ -56,6 +56,7 @@ def test_no_parts_matches_everything():
 def test_matches_exact_repo_path_and_symbol():
     data = _data({"repo": "Scribe", "path": "src/scribe/x.py", "symbol": "helper"})
     assert location_matches(data, {"repo": "Scribe"})
+    assert location_matches(data, {"repo": "scribe"})   # repo names: case never distinguishes (#2874)
     assert location_matches(data, {"path": "src/scribe/x.py"})
     assert location_matches(data, {"symbol": "helper"})
     assert location_matches(data, {"repo": "Scribe", "symbol": "helper"})
@@ -101,7 +102,8 @@ def test_blank_recorded_part_does_not_match_a_requested_one():
 def test_jsonpath_filters_within_one_locations_entry():
     expr = location_jsonpath({"repo": "Scribe", "symbol": "helper"})
     assert expr.startswith("$.locations[*] ? (")
-    assert '@.repo == "Scribe"' in expr
+    # repo: anchored, case-insensitive (#2874) — mirrors location_matches.
+    assert '@.repo like_regex "^Scribe$" flag "i"' in expr
     assert '@.symbol == "helper"' in expr
     assert " && " in expr
 
@@ -121,8 +123,9 @@ def test_jsonpath_quotes_values_as_json_literals():
     """A quote in a repo name must stay inside the literal, not end it."""
     nasty = 'we"ird'
     expr = location_jsonpath({"repo": nasty})
-    assert json.dumps(nasty) in expr
+    assert json.dumps("^" + nasty + "$") in expr      # the regex is a JSON literal too
     assert '\\"' in expr
+    assert json.dumps(nasty) in location_jsonpath({"symbol": nasty})
 
 
 def test_jsonpath_emits_parts_in_a_fixed_key_order():