Rules become findable: canon catalog, triggers, tiers, edges, retrieval, surfacing (milestone 307, steps 1–5) (#131)

Steps 1-5 of milestone 307. Design in note 3026; the step-6 true-up proposal is note 3061 and needs this deployed first.

Behaviour-neutral by construction: tier defaults to always_on, so every rule this instance already has keeps binding exactly as it did. That guarantee is the first case in tests/test_integration_rule_surfacing.py, against real Postgres.

Migrations 0087-0089 are additive. First boot backfills rule embeddings in the background. Plugin manifest at 0.1.47.

alembic/versions/0087_canonical_systems.py

@@ -0,0 +1,109 @@
+"""canonical_systems — the global area vocabulary, promoted from a constant
+to a table (milestone 307 step 1, decision note 3026)
+
+Revision ID: 0087
+Revises: 0086
+Create Date: 2026-08-26
+
+The eight standard area names already existed as `STANDARD_SYSTEMS`, a tuple in
+services/systems.py that milestone 297 seeds into a project at inception. A
+constant cannot be referenced: a rule that applies across projects has nothing
+to point at, because `systems.project_id` is NOT NULL and a family rule cannot
+be chained to one project's row. This makes the vocabulary a table so it can be
+a foreign key, and adds the nullable `systems.canonical_id` that maps a
+project's local System onto it.
+
+Deliberately no `user_id`: the catalog is GLOBAL so a shared project inherits
+the vocabulary rather than re-earning it. `record_systems` is untouched — it
+joins note_id/system_id and never sees this table, so no association data
+moves, and no System's own `name` is rewritten.
+
+The seed rows are written here verbatim rather than imported from the service:
+a migration is a historical record and must keep running unchanged after the
+service's list moves on.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0087"
+down_revision = "0086"
+branch_labels = None
+depends_on = None
+
+
+# (name, slug, description) — the milestone-297 vocabulary, with the slug the
+# service computes (canonical_slug: lowercase, "&" -> "and", non-alphanumerics
+# collapsed to "-"). Charters stay generic on purpose: a project refines its
+# own System's description, never this one. Nothing here names an app, a repo,
+# a vendor or a house convention — the catalog ships to every install (rule 115).
+_SEED = (
+    ("CI & Release", "ci-and-release",
+     "How the project is verified and shipped: pipelines, runners, image/artifact builds, release tagging and rollback."),
+    ("Auth & Access", "auth-and-access",
+     "Who may do what: identity, sessions/tokens, permissions and the scoping of every read and write to the right users."),
+    ("Data Model & Storage", "data-model-and-storage",
+     "What is stored and how it is shaped: the schema, migrations, serialisation and the services that own a table's lifecycle."),
+    ("API Surface", "api-surface",
+     "The doors into the capability: HTTP routes, tool/RPC surfaces, request parsing, error envelopes and their contracts."),
+    ("UI & Design", "ui-and-design",
+     "What people see and touch: views, components, client state, and the design tokens/recipes they are built from."),
+    ("Import & Export", "import-and-export",
+     "Data crossing the boundary: backups, exports, imports, sync with other systems, file formats."),
+    ("Background Jobs", "background-jobs",
+     "Work that runs without a request: schedulers, queues, periodic ticks, retention and maintenance."),
+    ("Observability", "observability",
+     "How the system reports on itself: logging, metrics, audit trails, health and diagnostics."),
+)
+
+
+def upgrade() -> None:
+    canonical_systems = op.create_table(
+        "canonical_systems",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("name", sa.Text(), nullable=False),
+        sa.Column("slug", sa.Text(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("order_index", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("deleted_batch_id", sa.Text(), nullable=True),
+    )
+    # Unique among LIVE rows only, so a soft-deleted entry doesn't block
+    # recreating or restoring the same area (the rules/topics convention).
+    op.create_index(
+        "uq_canonical_systems_slug", "canonical_systems", ["slug"],
+        unique=True, postgresql_where=sa.text("deleted_at IS NULL"),
+    )
+    op.bulk_insert(
+        canonical_systems,
+        [
+            {"name": name, "slug": slug, "description": description, "order_index": index}
+            for index, (name, slug, description) in enumerate(_SEED)
+        ],
+    )
+
+    op.add_column(
+        "systems",
+        sa.Column("canonical_id", sa.Integer(), nullable=True),
+    )
+    # SET NULL, not CASCADE: retiring a catalog entry must never delete a
+    # project's System along with it.
+    op.create_foreign_key(
+        "fk_systems_canonical_id", "systems", "canonical_systems",
+        ["canonical_id"], ["id"], ondelete="SET NULL",
+    )
+    op.create_index("ix_systems_canonical_id", "systems", ["canonical_id"])
+
+    # Existing Systems are left UNMAPPED on purpose. An exact-slug match would
+    # be safe, but a near miss ("CI & runners" vs "CI & Release") is a judgment
+    # call — those go through the propose/confirm path so a human approves each
+    # one, rather than being decided by a migration nobody reviews.
+
+
+def downgrade() -> None:
+    op.drop_index("ix_systems_canonical_id", table_name="systems")
+    op.drop_constraint("fk_systems_canonical_id", "systems", type_="foreignkey")
+    op.drop_column("systems", "canonical_id")
+    op.drop_index("uq_canonical_systems_slug", table_name="canonical_systems")
+    op.drop_table("canonical_systems")

alembic/versions/0088_rule_trigger_tier_tags_relations.py

@@ -0,0 +1,105 @@
+"""rules gain a trigger, a tier, canon tags and typed edges (milestone 307
+step 3, decision note 3026)
+
+Revision ID: 0088
+Revises: 0087
+Create Date: 2026-08-26
+
+A rule could not say WHEN it applies, WHICH area it is about, or WHAT other
+rule it belongs with. All three were being written as prose instead — a
+project's System description restating rule text, a rule's `why` naming the
+note that caused it, and two halves of one shape merged into a single row
+because either could surface without the other.
+
+Four additions, each replacing something that was already being said in words:
+
+- `when_to_apply` — the trigger. Nullable HERE and required at the service
+  layer, because existing rules have none and a migration cannot invent one.
+- `tier` — `always_on` (preloaded, as everything is today) or `conditional`
+  (reachable, surfaced when its trigger fires). Defaults to `always_on`, so
+  this migration changes NOTHING about which rules bind: an install upgrades
+  and every rule keeps arriving exactly as it did.
+- `arose_from_id` — the record that caused the rule, the edge notes and tasks
+  already have.
+- `rule_systems` / `rule_relations` — the canon tag and the typed edges.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0088"
+down_revision = "0087"
+branch_labels = None
+depends_on = None
+
+# Kept in one place so upgrade and the CHECK agree by construction (rule 36:
+# a whitelisted value means DROP + ADD CONSTRAINT in the same migration —
+# there is no prior constraint here, so the pair is created together).
+_TIERS = ("always_on", "conditional")
+_RELATION_KINDS = ("co_surfaces", "overrides", "elaborates")
+
+
+def _in_list(column: str, values: tuple[str, ...]) -> str:
+    return f"{column} IN (" + ", ".join(f"'{v}'" for v in values) + ")"
+
+
+def upgrade() -> None:
+    op.add_column("rules", sa.Column("when_to_apply", sa.Text(), nullable=True))
+    op.add_column(
+        "rules",
+        sa.Column("tier", sa.Text(), nullable=False, server_default="always_on"),
+    )
+    op.create_check_constraint("ck_rules_tier", "rules", _in_list("tier", _TIERS))
+
+    # SET NULL, not CASCADE: the record that prompted a rule can be trashed
+    # without taking the rule with it — provenance is a claim about history,
+    # and losing the source does not repeal the rule.
+    op.add_column("rules", sa.Column("arose_from_id", sa.BigInteger(), nullable=True))
+    op.create_foreign_key(
+        "fk_rules_arose_from_id", "rules", "notes",
+        ["arose_from_id"], ["id"], ondelete="SET NULL",
+    )
+
+    # Which global AREA a rule is about. Points at the canonical catalog, never
+    # at a project's `systems` row — a rule that spans projects cannot be
+    # chained to one project's vocabulary (0087).
+    op.create_table(
+        "rule_systems",
+        sa.Column("rule_id", sa.BigInteger(), sa.ForeignKey("rules.id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("canonical_id", sa.Integer(), sa.ForeignKey("canonical_systems.id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+    )
+    op.create_index("ix_rule_systems_canonical_id", "rule_systems", ["canonical_id"])
+
+    # Typed edges between rules. Each kind exists because its absence forced a
+    # workaround: co_surfaces (merging two rules into one row), overrides (a
+    # stricter project rule written as a duplicate), elaborates (a local
+    # addendum sitting beside its parent with nothing to say it is one).
+    op.create_table(
+        "rule_relations",
+        sa.Column("id", sa.BigInteger(), primary_key=True),
+        sa.Column("from_rule_id", sa.BigInteger(), sa.ForeignKey("rules.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("to_rule_id", sa.BigInteger(), sa.ForeignKey("rules.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("kind", sa.Text(), nullable=False),
+        sa.Column("note", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.CheckConstraint(_in_list("kind", _RELATION_KINDS), name="ck_rule_relations_kind"),
+        # A rule cannot relate to itself, and one pair carries a given kind
+        # once — a second row would surface the same rule twice.
+        sa.CheckConstraint("from_rule_id <> to_rule_id", name="ck_rule_relations_not_self"),
+        sa.UniqueConstraint("from_rule_id", "to_rule_id", "kind", name="uq_rule_relations_edge"),
+    )
+    op.create_index("ix_rule_relations_from", "rule_relations", ["from_rule_id"])
+    op.create_index("ix_rule_relations_to", "rule_relations", ["to_rule_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_rule_relations_to", table_name="rule_relations")
+    op.drop_index("ix_rule_relations_from", table_name="rule_relations")
+    op.drop_table("rule_relations")
+    op.drop_index("ix_rule_systems_canonical_id", table_name="rule_systems")
+    op.drop_table("rule_systems")
+    op.drop_constraint("fk_rules_arose_from_id", "rules", type_="foreignkey")
+    op.drop_column("rules", "arose_from_id")
+    op.drop_constraint("ck_rules_tier", "rules", type_="check")
+    op.drop_column("rules", "tier")
+    op.drop_column("rules", "when_to_apply")

alembic/versions/0089_rule_embeddings.py

@@ -0,0 +1,58 @@
+"""rule_embeddings — rules become findable by meaning (milestone 307 step 4,
+decision note 3026)
+
+Revision ID: 0089
+Revises: 0088
+Create Date: 2026-08-26
+
+Rules were the only major record type with no vector, so `search` could never
+return one and a rule could only ever arrive by being preloaded. That single
+fact is what made every rule compete for the same always-on budget.
+
+A sibling table rather than a generalisation of note_embeddings: the row could
+have been made polymorphic, but the SEARCH could not — semantic_search_notes is
+Note-specific scoping end to end, and a rule shares none of it. See the model
+docstring for the full reasoning.
+
+The vectors are DERIVED data. Nothing is backfilled here: the startup backfill
+regenerates them, which is also how a chunker-version bump is handled.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0089"
+down_revision = "0088"
+branch_labels = None
+depends_on = None
+
+# Matches note_embeddings — bge-small-en-v1.5, 384-dim unit-normalized.
+_EMBEDDING_DIM = 384
+
+
+def upgrade() -> None:
+    op.create_table(
+        "rule_embeddings",
+        sa.Column("rule_id", sa.BigInteger(), sa.ForeignKey("rules.id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("chunk_index", sa.Integer(), primary_key=True),
+        sa.Column("chunk_text", sa.Text(), nullable=False),
+        sa.Column("chunker_version", sa.Integer(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+    )
+    # The vector column is added by raw DDL for the same reason 0067 did it:
+    # the type comes from the pgvector extension, not from SQLAlchemy's
+    # type system.
+    op.execute(f"ALTER TABLE rule_embeddings ADD COLUMN embedding vector({_EMBEDDING_DIM}) NOT NULL")
+    # HNSW for cosine distance — matches Vector.cosine_distance (`<=>`), so the
+    # search is an indexed ORDER BY ... LIMIT k rather than a full scan.
+    op.execute(
+        """
+        CREATE INDEX ix_rule_embeddings_embedding_hnsw
+            ON rule_embeddings
+         USING hnsw (embedding vector_cosine_ops)
+        """
+    )
+
+
+def downgrade() -> None:
+    op.execute("DROP INDEX IF EXISTS ix_rule_embeddings_embedding_hnsw")
+    op.drop_table("rule_embeddings")

frontend/src/api/canonicalSystems.ts

@@ -0,0 +1,81 @@
+/**
+ * Canonical systems — the GLOBAL area vocabulary every project's Systems can
+ * map onto (milestone 307).
+ *
+ * The mapping is an ASSOCIATION, never a rename: a project's System keeps the
+ * name the project gave it, and `canonical_id` only records which shared area
+ * it is an instance of. An unmapped System is fully usable — the catalog is a
+ * convergence aid, not a gate.
+ */
+import { apiGet, apiPost, apiPatch, apiPut } from "@/api/client";
+
+export interface CanonicalSystem {
+  id: number;
+  name: string;
+  /** The match key: lowercase, "&" folded to "and", punctuation collapsed. */
+  slug: string;
+  description: string | null;
+  order_index: number;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+/**
+ * A suggested mapping. `basis` is the whole point of showing it:
+ * - `exact`   — the names differ only in spelling. Mechanical.
+ * - `overlap` — they share a meaningful word. A judgment call the reviewer is
+ *   making, and it must never be presented as if it were the first.
+ */
+export interface CanonicalMatch {
+  id: number;
+  name: string;
+  basis: "exact" | "overlap";
+  score?: number;
+}
+
+export interface MappingProposal {
+  system_id: number;
+  system_name: string;
+  canonical_id: number;
+  canonical_name: string;
+  basis: "exact" | "overlap";
+  score: number;
+}
+
+export async function listCanonicalSystems(): Promise<CanonicalSystem[]> {
+  const data = await apiGet<{ canonical_systems: CanonicalSystem[] }>(
+    "/api/canonical-systems",
+  );
+  return data.canonical_systems;
+}
+
+/** Admin only — a global list anyone can extend stops being shared. */
+export async function createCanonicalSystem(data: {
+  name: string;
+  description?: string;
+}): Promise<CanonicalSystem> {
+  return apiPost("/api/canonical-systems", data);
+}
+
+export async function updateCanonicalSystem(
+  id: number,
+  data: Partial<{ name: string; description: string; order_index: number }>,
+): Promise<CanonicalSystem> {
+  return apiPatch(`/api/canonical-systems/${id}`, data);
+}
+
+/** Proposals for a project's UNMAPPED Systems. Reads only — nothing applied. */
+export async function proposeMappings(projectId: number): Promise<MappingProposal[]> {
+  const data = await apiGet<{ proposals: MappingProposal[] }>(
+    `/api/projects/${projectId}/canonical-proposals`,
+  );
+  return data.proposals;
+}
+
+/** Apply or clear one mapping. `null` unmaps. */
+export async function mapSystem(
+  systemId: number,
+  canonicalId: number | null,
+): Promise<{ id: number; canonical_id: number | null }> {
+  return apiPut(`/api/systems/${systemId}/canonical`, { canonical_id: canonicalId });
+}

frontend/src/api/rulebooks.ts

@@ -1,5 +1,24 @@
 import { apiGet, apiPost, apiPatch, apiDelete } from "@/api/client";
 
+/** How a rule reaches a session (milestone 307). */
+export type RuleTier = "always_on" | "conditional";
+
+/**
+ * A typed edge between two rules. Each kind exists because its absence forced
+ * a workaround: merging two rules into one row, writing an override as a
+ * near-copy, or leaving a local addendum with nothing to say it is one.
+ */
+export type RuleRelationKind = "co_surfaces" | "overrides" | "elaborates";
+
+export interface RuleRelation {
+  id: number;
+  kind: RuleRelationKind;
+  /** The rule at the OTHER end. */
+  rule_id: number;
+  direction: "outgoing" | "incoming";
+  note: string;
+}
+
 export interface Rulebook {
   id: number;
   owner_user_id: number;
@@ -26,35 +45,53 @@ export interface Rule {
   project_id: number | null;
   title: string;
   statement: string;
+  /** WHEN this rule fires — the trigger, not the instruction. */
+  when_to_apply: string;
+  /**
+   * always_on preloads into every session; conditional is reachable and
+   * surfaced when its trigger fires. A rule with no tier set behaves as
+   * always_on, which is how every rule behaved before this existed.
+   */
+  tier: RuleTier;
   why: string;
   how_to_apply: string;
+  /** The note or task that caused this rule, if one was recorded. */
+  arose_from_id: number | null;
   order_index: number;
   created_at: string | null;
   updated_at: string | null;
+  /** Present only when the rule has them (the server omits empty keys). */
+  systems?: { id: number; name: string }[];
+  relations?: RuleRelation[];
 }
 
+/**
+ * A rule as a LIST ROW — services.rulebooks.rule_brief's output. Carries the
+ * age deliberately: a rule written before the capability it duplicates is
+ * otherwise indistinguishable, at a glance, from one still doing work.
+ */
 export interface RuleHeader {
   id: number;
   title: string;
   statement: string;
   topic_id: number | null;
+  tier: RuleTier;
+  /** A date (YYYY-MM-DD), not a timestamp. */
+  updated_at: string | null;
+  when_to_apply?: string;
+  arose_from_id?: number;
 }
 
 export interface ApplicableRules {
-  rules: {
-    id: number;
-    title: string;
-    statement: string;
-    topic_id: number;
+  // Both lists are rule_brief's output — the SAME builder, so they are
+  // described the same way here rather than as two hand-written shapes that
+  // drift from it and from each other (which is what the server side had).
+  rules: (RuleHeader & {
     topic_title: string;
     rulebook_id: number;
     rulebook_title: string;
-  }[];
-  project_rules: {
-    id: number;
-    title: string;
-    statement: string;
-  }[];
+  })[];
+  project_rules: RuleHeader[];
   suppressed_rules: {
     id: number;
     title: string;
@@ -133,14 +170,39 @@ export async function getRule(id: number): Promise<Rule> {
   return apiGet(`/api/rules/${id}`);
 }
 
-export async function createRule(topicId: number, data: { title: string; statement: string; why?: string; how_to_apply?: string; order_index?: number }): Promise<Rule> {
+/** The fields both write paths accept. `system_ids` REPLACES a rule's areas. */
+export interface RuleWrite {
+  title: string;
+  statement: string;
+  when_to_apply: string;
+  tier: RuleTier;
+  why: string;
+  how_to_apply: string;
+  order_index: number;
+  system_ids: number[];
+  arose_from_id: number | null;
+}
+
+export async function createRule(topicId: number, data: Partial<RuleWrite> & { title: string; statement: string }): Promise<Rule> {
   return apiPost(`/api/rulebook-topics/${topicId}/rules`, data);
 }
 
-export async function updateRule(id: number, data: Partial<{ title: string; statement: string; why: string; how_to_apply: string; order_index: number }>): Promise<Rule> {
+export async function updateRule(id: number, data: Partial<RuleWrite>): Promise<Rule> {
   return apiPatch(`/api/rules/${id}`, data);
 }
 
+/** Draw a typed edge from one rule to another. Idempotent. */
+export async function relateRules(
+  fromRuleId: number,
+  data: { to_rule_id: number; kind: RuleRelationKind; note?: string },
+): Promise<{ id: number }> {
+  return apiPost(`/api/rules/${fromRuleId}/relations`, data);
+}
+
+export async function unrelateRules(relationId: number): Promise<void> {
+  return apiDelete(`/api/rule-relations/${relationId}`);
+}
+
 export async function deleteRule(id: number): Promise<void> {
   return apiDelete(`/api/rules/${id}`);
 }
@@ -161,7 +223,7 @@ export async function getProjectApplicableRules(projectId: number): Promise<Appl
 
 export async function createProjectRule(
   projectId: number,
-  data: { statement: string; title?: string; why?: string; how_to_apply?: string },
+  data: Partial<RuleWrite> & { statement: string },
 ): Promise<Rule> {
   return apiPost(`/api/projects/${projectId}/rules`, data);
 }

frontend/src/api/systems.ts

@@ -1,9 +1,15 @@
 import { apiGet, apiPost, apiPatch, apiDelete } from "@/api/client";
+import type { CanonicalMatch } from "@/api/canonicalSystems";
 
 export interface System {
   id: number;
   project_id: number;
   name: string;
+  /**
+   * The global area this System is an instance of, or null. Null is a valid
+   * resting state — a project-specific area should stay unmapped.
+   */
+  canonical_id: number | null;
   description: string;
   color: string | null;
   status: "active" | "archived";
@@ -18,10 +24,23 @@ export async function listSystems(projectId: number): Promise<System[]> {
   return data.systems;
 }
 
+/**
+ * A created System, plus the catalog's answer about its name. An `exact`
+ * catalog hit is applied by the server and arrives as a populated
+ * `canonical_id`; an `overlap` is only OFFERED, and comes back here for the
+ * caller to accept or ignore.
+ *
+ * A same-named System in this project is a 409 ApiError carrying
+ * `{duplicate, existing_id}` — the same gate the MCP door enforces (#2482).
+ */
+export interface CreatedSystem extends System {
+  canonical_suggestion?: CanonicalMatch;
+}
+
 export async function createSystem(
   projectId: number,
-  data: { name: string; description?: string; color?: string },
-): Promise<System> {
+  data: { name: string; description?: string; color?: string; canonical_id?: number },
+): Promise<CreatedSystem> {
   return apiPost(`/api/projects/${projectId}/systems`, data);
 }
 

frontend/src/components/SystemsSection.vue

@@ -1,14 +1,18 @@
 <script setup lang="ts">
 import { ref, computed, onMounted, watch } from "vue";
 import { useSystemsStore } from "@/stores/systems";
+import { useCanonicalSystemsStore } from "@/stores/canonicalSystems";
 import { useToastStore } from "@/stores/toast";
 import { getProjectIssues } from "@/api/systems";
 import type { System, TaskLike } from "@/api/systems";
+import type { CanonicalMatch } from "@/api/canonicalSystems";
+import { apiErrorMessage } from "@/api/client";
 import { Pencil, Trash2, Archive, ArchiveRestore } from "lucide-vue-next";
 
 const props = defineProps<{ projectId: number }>();
 
 const store = useSystemsStore();
+const canon = useCanonicalSystemsStore();
 const toast = useToastStore();
 
 const error = ref<string | null>(null);
@@ -19,14 +23,26 @@ const issues = ref<TaskLike[]>([]);
 const showCreate = ref(false);
 const newName = ref("");
 const newDescription = ref("");
+// The global area, chosen explicitly. A PICKER rather than a live matcher on
+// purpose: reproducing the server's slug rule in TypeScript would give this
+// feature two matchers to keep in step, which is the exact drift the catalog
+// exists to end. The server still applies an exact hit on submit.
+const newCanonicalId = ref<number | null>(null);
 const creating = ref(false);
+// An `overlap` the server offered after a create — an offer, never applied.
+const suggestion = ref<{ systemId: number; match: CanonicalMatch } | null>(null);
 
 // Edit state
 const editingId = ref<number | null>(null);
 const editName = ref("");
 const editDescription = ref("");
+const editCanonicalId = ref<number | null>(null);
 const savingEdit = ref(false);
 
+// Mapping review
+const showReview = ref(false);
+const reviewBusy = ref<number | null>(null);
+
 // Delete confirmation
 const deletingSystem = ref<System | null>(null);
 
@@ -37,6 +53,12 @@ const visibleSystems = computed(() =>
   showArchived.value ? systems.value : activeSystems.value,
 );
 
+const proposals = computed(() => canon.proposalsByProject[props.projectId] ?? []);
+
+function areaName(system: System): string | null {
+  return canon.byId(system.canonical_id)?.name ?? null;
+}
+
 async function load() {
   error.value = null;
   try {
@@ -49,6 +71,14 @@ async function load() {
   } catch {
     issues.value = [];
   }
+  // Both fail soft: the catalog is a naming aid, and a review prompt that
+  // cannot load must not take the Systems list down with it.
+  await canon.fetchCatalog();
+  try {
+    await canon.fetchProposals(props.projectId);
+  } catch {
+    /* no proposals shown */
+  }
 }
 
 onMounted(load);
@@ -58,12 +88,14 @@ function openCreate() {
   showCreate.value = true;
   newName.value = "";
   newDescription.value = "";
+  newCanonicalId.value = null;
 }
 
 function cancelCreate() {
   showCreate.value = false;
   newName.value = "";
   newDescription.value = "";
+  newCanonicalId.value = null;
 }
 
 async function submitCreate() {
@@ -71,23 +103,60 @@ async function submitCreate() {
   if (!name || creating.value) return;
   creating.value = true;
   try {
-    await store.createSystem(props.projectId, {
+    const created = await store.createSystem(props.projectId, {
       name,
       description: newDescription.value.trim() || undefined,
+      canonical_id: newCanonicalId.value ?? undefined,
     });
     cancelCreate();
-    toast.show("System created");
-  } catch {
-    toast.show("Failed to create system", "error");
+    if (created.canonical_suggestion) {
+      // An overlap: shown as an offer beside the new System, never applied.
+      suggestion.value = { systemId: created.id, match: created.canonical_suggestion };
+    }
+    toast.show(
+      created.canonical_id
+        ? `System created and filed under ${canon.byId(created.canonical_id)?.name}`
+        : "System created",
+    );
+  } catch (e) {
+    // 409 = this project already has that System. Say WHICH one, so the
+    // answer is actionable rather than "it didn't work".
+    toast.show(apiErrorMessage(e, "Failed to create system"), "error");
   } finally {
     creating.value = false;
   }
 }
 
+async function acceptSuggestion() {
+  const pending = suggestion.value;
+  if (!pending) return;
+  suggestion.value = null;
+  try {
+    await canon.mapSystem(props.projectId, pending.systemId, pending.match.id);
+    await store.fetchSystems(props.projectId);
+    toast.show(`Filed under ${pending.match.name}`);
+  } catch {
+    /* the store already reported it */
+  }
+}
+
+async function applyProposal(systemId: number, canonicalId: number) {
+  reviewBusy.value = systemId;
+  try {
+    await canon.mapSystem(props.projectId, systemId, canonicalId);
+    await store.fetchSystems(props.projectId);
+  } catch {
+    /* the store already reported it */
+  } finally {
+    reviewBusy.value = null;
+  }
+}
+
 function startEdit(system: System) {
   editingId.value = system.id;
   editName.value = system.name;
   editDescription.value = system.description;
+  editCanonicalId.value = system.canonical_id;
 }
 
 function cancelEdit() {
@@ -103,6 +172,12 @@ async function submitEdit(system: System) {
       name,
       description: editDescription.value.trim(),
     });
+    // The mapping is a separate write with its own validation — one column,
+    // one writer (services/canonical_systems.set_system_canonical).
+    if (editCanonicalId.value !== system.canonical_id) {
+      await canon.mapSystem(props.projectId, system.id, editCanonicalId.value);
+      await store.fetchSystems(props.projectId);
+    }
     editingId.value = null;
     toast.show("System updated");
   } catch {
@@ -161,6 +236,65 @@ async function confirmDelete() {
       </ul>
     </div>
 
+    <!-- Mapping review. Only appears when there is something to decide, and
+         it says HOW MANY rather than nagging with a permanent banner. -->
+    <div v-if="proposals.length" class="area-review">
+      <button class="area-review-head" @click="showReview = !showReview">
+        <span class="area-review-count">{{ proposals.length }}</span>
+        {{ proposals.length === 1 ? "system" : "systems" }} may belong to a shared area
+        <span class="area-review-chev">{{ showReview ? "▾" : "▸" }}</span>
+      </button>
+      <ul v-if="showReview" class="area-proposals">
+        <li v-for="p in proposals" :key="p.system_id" class="area-proposal">
+          <div class="area-proposal-text">
+            <span class="area-proposal-name">{{ p.system_name }}</span>
+            <span class="area-proposal-arrow" aria-hidden="true">→</span>
+            <span class="area-proposal-target">{{ p.canonical_name }}</span>
+            <!-- The basis is the decision the reviewer is making: `exact`
+                 differs only in spelling, `overlap` is a judgment call.
+                 Showing them identically is how a wrong mapping is waved
+                 through, so they never share a style. -->
+            <span
+              class="area-basis"
+              :class="p.basis === 'exact' ? 'area-basis--exact' : 'area-basis--overlap'"
+              :title="
+                p.basis === 'exact'
+                  ? 'Same name up to spelling — safe to accept.'
+                  : 'Shares a word. Accept only if it is really the same area.'
+              "
+            >{{ p.basis === "exact" ? "same name" : "similar" }}</span>
+          </div>
+          <div class="area-proposal-actions">
+            <button
+              class="btn-primary btn-compact"
+              :disabled="reviewBusy === p.system_id"
+              @click="applyProposal(p.system_id, p.canonical_id)"
+            >
+              {{ reviewBusy === p.system_id ? "Filing…" : "File here" }}
+            </button>
+            <button
+              class="btn-ghost btn-compact"
+              @click="canon.dismissProposal(props.projectId, p.system_id)"
+            >
+              Not this
+            </button>
+          </div>
+        </li>
+      </ul>
+    </div>
+
+    <!-- An overlap offered by the server after a create. Never applied. -->
+    <div v-if="suggestion" class="area-offer">
+      <span>
+        Is this the same area as
+        <strong>{{ suggestion.match.name }}</strong>?
+      </span>
+      <div class="area-proposal-actions">
+        <button class="btn-primary btn-compact" @click="acceptSuggestion">File it there</button>
+        <button class="btn-ghost btn-compact" @click="suggestion = null">No, it's ours</button>
+      </div>
+    </div>
+
     <!-- Toolbar -->
     <div class="systems-toolbar">
       <button v-if="!showCreate" class="btn-ghost btn-inline btn-add-system" @click="openCreate">
@@ -189,6 +323,20 @@ async function confirmDelete() {
         placeholder="What is this subsystem responsible for? (optional)"
         aria-label="System description"
       ></textarea>
+      <label v-if="canon.catalog.length" class="area-field">
+        <span class="area-label">Shared area</span>
+        <select v-model="newCanonicalId" class="fs-input area-select" aria-label="Shared area">
+          <option :value="null">None — specific to this project</option>
+          <option v-for="entry in canon.catalog" :key="entry.id" :value="entry.id">
+            {{ entry.name }}
+          </option>
+        </select>
+        <!-- .field-hint is the shared hint class beside .fs-input
+             (components.css) — not restated scoped. -->
+        <span class="field-hint">
+          Files this system under an area shared by every project. Your name stays as you typed it.
+        </span>
+      </label>
       <div class="system-form-actions">
         <button type="submit" class="btn-primary btn-compact" :disabled="!newName.trim() || creating">
           {{ creating ? "Creating…" : "Create" }}
@@ -240,6 +388,15 @@ async function confirmDelete() {
               placeholder="Description (optional)"
               aria-label="System description"
             ></textarea>
+            <label v-if="canon.catalog.length" class="area-field">
+              <span class="area-label">Shared area</span>
+              <select v-model="editCanonicalId" class="fs-input area-select" aria-label="Shared area">
+                <option :value="null">None — specific to this project</option>
+                <option v-for="entry in canon.catalog" :key="entry.id" :value="entry.id">
+                  {{ entry.name }}
+                </option>
+              </select>
+            </label>
             <div class="system-form-actions">
               <button type="submit" class="btn-primary btn-compact" :disabled="!editName.trim() || savingEdit">
                 {{ savingEdit ? "Saving…" : "Save" }}
@@ -264,6 +421,13 @@ async function confirmDelete() {
                 :title="`${system.open_issue_count} open issue(s)`"
               >{{ system.open_issue_count }} open</span>
               <span v-if="system.status === 'archived'" class="archived-badge">Archived</span>
+              <!-- Not a TagPill: that recipe prefixes "#" and means a tag.
+                   This is the shared AREA this system is an instance of. -->
+              <span
+                v-if="areaName(system)"
+                class="area-chip"
+                :title="`Filed under the shared area “${areaName(system)}” — records and rules about this area line up across projects.`"
+              >{{ areaName(system) }}</span>
             </div>
             <p v-if="system.description" class="system-description">{{ system.description }}</p>
           </div>
@@ -335,6 +499,91 @@ async function confirmDelete() {
 .issue-systems { display: flex; gap: 0.25rem; flex-shrink: 0; flex-wrap: wrap; }
 .issue-sys-chip { font-size: 0.66rem; color: var(--fs-text-secondary); background: var(--fs-surface-raised); border-radius: 999px; padding: 0.05rem 0.4rem; }
 
+/* ── Shared-area mapping (milestone 307) ──────────────────────────
+   The review is a disclosure, not a banner: it exists only while there is
+   something to decide, and collapses to one line until opened. */
+.area-review {
+  border: 1px solid var(--fs-border-color);
+  border-radius: var(--fs-radius-lg);
+  background: var(--fs-surface-raised);
+}
+.area-review-head {
+  display: flex;
+  align-items: center;
+  gap: var(--fs-space-2);
+  width: 100%;
+  padding: var(--fs-space-3);
+  background: none;
+  border: none;
+  color: var(--fs-text-secondary);
+  font: inherit;
+  font-size: 0.82rem;
+  text-align: left;
+  cursor: pointer;
+  border-radius: var(--fs-radius-lg);
+}
+.area-review-head:hover { color: var(--fs-text-primary); }
+.area-review-head:focus-visible { outline: none; box-shadow: var(--fs-focus-ring); }
+.area-review-count {
+  background: var(--fs-accent-soft);
+  color: var(--fs-accent);
+  border-radius: var(--fs-radius-pill);
+  padding: 0.05rem 0.45rem;
+  font-variant-numeric: tabular-nums;
+}
+.area-review-chev { margin-left: auto; color: var(--fs-text-tertiary); }
+
+.area-proposals { list-style: none; margin: 0; padding: 0 var(--fs-space-3) var(--fs-space-3); display: flex; flex-direction: column; gap: var(--fs-space-2); }
+.area-proposal {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fs-space-3);
+  flex-wrap: wrap;
+  padding: var(--fs-space-2) var(--fs-space-3);
+  background: var(--fs-surface-page);
+  border: 1px solid var(--fs-border-color);
+  border-radius: var(--fs-radius-md);
+}
+.area-proposal-text { display: flex; align-items: center; gap: var(--fs-space-2); flex-wrap: wrap; font-size: 0.85rem; min-width: 0; }
+.area-proposal-name { color: var(--fs-text-primary); }
+.area-proposal-arrow { color: var(--fs-text-tertiary); }
+.area-proposal-target { color: var(--fs-accent); }
+.area-proposal-actions { display: flex; gap: var(--fs-space-2); flex-shrink: 0; }
+
+/* The two bases must never look alike — one is mechanical, the other is the
+   reviewer's judgment, and that difference is the whole decision. */
+.area-basis { font-size: 0.68rem; border-radius: var(--fs-radius-sm); padding: 0.05rem 0.4rem; }
+.area-basis--exact { background: var(--fs-status-done-bg); color: var(--fs-status-done); }
+.area-basis--overlap { background: var(--fs-priority-medium-bg); color: var(--fs-priority-medium); }
+
+.area-offer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fs-space-3);
+  flex-wrap: wrap;
+  padding: var(--fs-space-3);
+  font-size: 0.85rem;
+  color: var(--fs-text-secondary);
+  background: var(--fs-accent-faint);
+  border: 1px solid var(--fs-border-color);
+  border-radius: var(--fs-radius-lg);
+}
+
+.area-field { display: flex; flex-direction: column; gap: 0.3rem; }
+.area-label { font-size: 0.78rem; color: var(--fs-text-tertiary); }
+.area-select { box-sizing: border-box; width: 100%; }
+
+.area-chip {
+  font-size: 0.66rem;
+  color: var(--fs-accent);
+  background: var(--fs-accent-soft);
+  border-radius: var(--fs-radius-pill);
+  padding: 0.05rem 0.45rem;
+  white-space: nowrap;
+}
+
 /* ── Toolbar ──────────────────────────────────────────────────── */
 .systems-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 0.75rem; }
 .btn-add-system {

frontend/src/components/rules/ProjectRulesTab.vue

@@ -27,7 +27,10 @@ const expandedRuleIds = ref<Set<number>>(new Set());
 const ruleDetails = ref<Record<number, { why: string; how_to_apply: string }>>({});
 
 const showProjectRuleForm = ref(false);
-const newProjectRule = ref({ title: "", statement: "", why: "", how_to_apply: "" });
+const newProjectRule = ref({
+  title: "", statement: "", why: "", how_to_apply: "",
+  when_to_apply: "", tier: "always_on" as "always_on" | "conditional",
+});
 
 async function load() {
   applicable.value = await getProjectApplicableRules(props.projectId);
@@ -90,14 +93,20 @@ interface RulebookGroup {
 function groupByRulebookAndTopic(rules: ApplicableRules["rules"]): RulebookGroup[] {
   const byRulebook = new Map<number, RulebookGroup>();
   for (const r of rules) {
+    // A rule carries topic_id XOR project_id. Only rulebook-scoped rules reach
+    // this list, so a null topic would be a server-side contradiction — skip
+    // it rather than widen the group's type to accommodate a case that means
+    // something is wrong upstream.
+    if (r.topic_id === null) continue;
+    const topicId = r.topic_id;
     let rb = byRulebook.get(r.rulebook_id);
     if (!rb) {
       rb = { rulebook_id: r.rulebook_id, rulebook_title: r.rulebook_title, topics: [] };
       byRulebook.set(r.rulebook_id, rb);
     }
-    let topic = rb.topics.find((t) => t.topic_id === r.topic_id);
+    let topic = rb.topics.find((t) => t.topic_id === topicId);
     if (!topic) {
-      topic = { topic_id: r.topic_id, topic_title: r.topic_title, rules: [] };
+      topic = { topic_id: topicId, topic_title: r.topic_title, rules: [] };
       rb.topics.push(topic);
     }
     topic.rules.push(r);
@@ -113,8 +122,13 @@ async function submitProjectRule() {
     title: newProjectRule.value.title.trim() || undefined,
     why: newProjectRule.value.why.trim() || undefined,
     how_to_apply: newProjectRule.value.how_to_apply.trim() || undefined,
+    when_to_apply: newProjectRule.value.when_to_apply.trim() || undefined,
+    tier: newProjectRule.value.tier,
   });
-  newProjectRule.value = { title: "", statement: "", why: "", how_to_apply: "" };
+  newProjectRule.value = {
+    title: "", statement: "", why: "", how_to_apply: "",
+    when_to_apply: "", tier: "always_on",
+  };
   showProjectRuleForm.value = false;
   await load();
 }
@@ -219,6 +233,24 @@ watch(() => props.projectId, load);
           placeholder="Statement (required) — the actionable instruction, 1-2 sentences"
           rows="2"
         ></textarea>
+        <textarea
+          v-model="newProjectRule.when_to_apply"
+          placeholder="When to apply — the trigger, not the instruction"
+          rows="2"
+        ></textarea>
+        <div class="tier-row">
+          <label>
+            <input v-model="newProjectRule.tier" type="radio" value="always_on" />
+            Always on
+          </label>
+          <label>
+            <input v-model="newProjectRule.tier" type="radio" value="conditional" />
+            Conditional
+          </label>
+          <span class="tier-hint">
+            Conditional if you had to name a system, an artifact or a moment to state the trigger.
+          </span>
+        </div>
         <textarea
           v-model="newProjectRule.why"
           placeholder="Why (optional) — the rationale"
@@ -345,6 +377,11 @@ watch(() => props.projectId, load);
 </template>
 
 <style scoped>
+.tier-row { display: flex; align-items: center; gap: 0.75rem; flex-wrap: wrap; font-size: 0.85rem; }
+.tier-row label { display: inline-flex; align-items: center; gap: 0.3rem; }
+.tier-row input { accent-color: var(--fs-accent); }
+.tier-hint { flex: 1; min-width: 12rem; font-size: 0.75rem; color: var(--fs-text-tertiary); }
+
 .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; }

frontend/src/components/rules/RuleEditorSlideOver.vue

@@ -1,16 +1,41 @@
 <script setup lang="ts">
-import { ref, watch, onMounted } from "vue";
+import { computed, ref, watch, onMounted } from "vue";
 import { useRulebooksStore } from "@/stores/rulebooks";
+import { useCanonicalSystemsStore } from "@/stores/canonicalSystems";
+import type { RuleTier } from "@/api/rulebooks";
 
 const props = defineProps<{ ruleId: number | null; topicId: number | null }>();
 const emit = defineEmits<{ close: [] }>();
 
 const store = useRulebooksStore();
+const canon = useCanonicalSystemsStore();
 const title = ref("");
 const statement = ref("");
+const whenToApply = ref("");
+const tier = ref<RuleTier>("always_on");
+const systemIds = ref<number[]>([]);
 const why = ref("");
 const howToApply = ref("");
 
+const relations = computed(() => store.currentRule?.relations ?? []);
+
+// The label a reader needs to judge an edge, not the stored token.
+const RELATION_LABEL: Record<string, { outgoing: string; incoming: string }> = {
+  co_surfaces: { outgoing: "arrives with", incoming: "arrives with" },
+  overrides: { outgoing: "overrides", incoming: "is overridden by" },
+  elaborates: { outgoing: "elaborates", incoming: "is elaborated by" },
+};
+
+function relationLabel(kind: string, direction: "outgoing" | "incoming") {
+  return RELATION_LABEL[kind]?.[direction] ?? kind;
+}
+
+function toggleSystem(id: number) {
+  const at = systemIds.value.indexOf(id);
+  if (at >= 0) systemIds.value.splice(at, 1);
+  else systemIds.value.push(id);
+}
+
 const isCreating = ref(props.ruleId === null);
 
 async function load() {
@@ -20,15 +45,22 @@ async function load() {
     if (r) {
       title.value = r.title;
       statement.value = r.statement;
+      whenToApply.value = r.when_to_apply || "";
+      tier.value = r.tier || "always_on";
+      systemIds.value = (r.systems ?? []).map((sys) => sys.id);
       why.value = r.why || "";
       howToApply.value = r.how_to_apply || "";
     }
   } else {
     title.value = "";
     statement.value = "";
+    whenToApply.value = "";
+    tier.value = "always_on";
+    systemIds.value = [];
     why.value = "";
     howToApply.value = "";
   }
+  await canon.fetchCatalog();
 }
 
 async function save() {
@@ -36,16 +68,21 @@ async function save() {
     emit("close");
     return;
   }
+  const fields = {
+    title: title.value,
+    statement: statement.value,
+    when_to_apply: whenToApply.value,
+    tier: tier.value,
+    // Always sent, so clearing the last area actually clears it — the server
+    // reads a list as "these ARE the areas now".
+    system_ids: systemIds.value,
+    why: why.value,
+    how_to_apply: howToApply.value,
+  };
   if (isCreating.value && props.topicId !== null) {
-    await store.createRule(props.topicId, {
-      title: title.value, statement: statement.value,
-      why: why.value, how_to_apply: howToApply.value,
-    });
+    await store.createRule(props.topicId, fields);
   } else if (props.ruleId !== null) {
-    await store.updateRule(props.ruleId, {
-      title: title.value, statement: statement.value,
-      why: why.value, how_to_apply: howToApply.value,
-    });
+    await store.updateRule(props.ruleId, fields);
   }
   emit("close");
 }
@@ -77,6 +114,69 @@ watch(() => props.ruleId, load);
         Statement <span class="required">*</span>
         <textarea v-model="statement" rows="3" placeholder="The actionable instruction (1-2 sentences)." />
       </label>
+      <label>
+        When to apply
+        <textarea
+          v-model="whenToApply"
+          rows="2"
+          placeholder="The trigger, not the instruction — “before any git push”, “when a release is being cut”."
+        />
+      </label>
+
+      <fieldset class="tier">
+        <legend>How it reaches a session</legend>
+        <label class="tier-opt">
+          <input v-model="tier" type="radio" value="always_on" />
+          <span>
+            <strong>Always on</strong>
+            — loaded into every session.
+          </span>
+        </label>
+        <label class="tier-opt">
+          <input v-model="tier" type="radio" value="conditional" />
+          <span>
+            <strong>Conditional</strong>
+            — arrives when its trigger fires.
+          </span>
+        </label>
+        <p class="tier-test">
+          The test: can you name the trigger <em>without</em> naming a system, an artifact type
+          or a moment? If the honest answer is “whenever you are working”, it is always on.
+          Conditional costs nothing when it is irrelevant, which is what lets it be as long as
+          it needs to be.
+        </p>
+      </fieldset>
+
+      <fieldset v-if="canon.catalog.length" class="areas">
+        <legend>Areas this rule is about</legend>
+        <label v-for="entry in canon.catalog" :key="entry.id" class="area-opt">
+          <input
+            type="checkbox"
+            :checked="systemIds.includes(entry.id)"
+            @change="toggleSystem(entry.id)"
+          />
+          <span>{{ entry.name }}</span>
+        </label>
+        <p class="tier-test">
+          What lets this rule reach a project working in that area.
+        </p>
+      </fieldset>
+
+      <section v-if="relations.length" class="relations">
+        <h3>Related rules</h3>
+        <ul>
+          <li v-for="rel in relations" :key="rel.id" class="relation">
+            <span class="relation-kind">{{ relationLabel(rel.kind, rel.direction) }}</span>
+            <span class="relation-target">rule #{{ rel.rule_id }}</span>
+            <span v-if="rel.note" class="relation-note">{{ rel.note }}</span>
+          </li>
+        </ul>
+        <p class="tier-test">
+          Rules that <em>fail together</em> are linked, never merged — a merged rule cannot be
+          cited, surfaced or suppressed a clause at a time.
+        </p>
+      </section>
+
       <label>
         Why
         <textarea v-model="why" rows="4" placeholder="Rationale — the reason this rule exists." />
@@ -118,6 +218,19 @@ input, textarea {
   padding: 0.5rem; font: inherit;
   font-family: inherit;
 }
+fieldset { border: 1px solid var(--fs-border-color); border-radius: var(--fs-radius-md); padding: 0.75rem; margin-bottom: 1rem; }
+legend { padding: 0 0.35rem; font-size: 0.8rem; color: var(--fs-text-tertiary); }
+.tier-opt, .area-opt { display: flex; align-items: flex-start; gap: 0.5rem; margin-bottom: 0.4rem; font-size: 0.88rem; }
+.tier-opt input, .area-opt input { width: auto; margin-top: 0.2rem; accent-color: var(--fs-accent); }
+.tier-test { margin: 0.5rem 0 0; font-size: 0.78rem; color: var(--fs-text-tertiary); line-height: 1.45; }
+
+.relations h3 { margin: 0 0 0.5rem; font-size: 0.85rem; color: var(--fs-text-secondary); }
+.relations ul { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 0.35rem; }
+.relation { display: flex; align-items: baseline; gap: 0.4rem; flex-wrap: wrap; font-size: 0.85rem; }
+.relation-kind { color: var(--fs-accent); }
+.relation-target { color: var(--fs-text-primary); }
+.relation-note { width: 100%; font-size: 0.78rem; color: var(--fs-text-tertiary); }
+
 .trash, .close { background: none; border: none; cursor: pointer; opacity: 0.6; font-size: 1.25em; }
 .trash:hover, .close:hover { opacity: 1; }
 </style>

frontend/src/components/rules/RuleListPane.vue

@@ -13,8 +13,17 @@ const emit = defineEmits<{
     <header><h2>Rules</h2></header>
     <ul>
       <li v-for="r in rules" :key="r.id" @click="emit('open-rule', r.id)">
-        <div class="title">{{ r.title }}</div>
+        <div class="title">
+          {{ r.title }}
+          <!-- Only conditional is marked: always-on is the default and
+               badging every row would say nothing. -->
+          <span v-if="r.tier === 'conditional'" class="tier-chip" title="Arrives when its trigger fires, rather than in every session">conditional</span>
+        </div>
         <div class="statement">{{ r.statement }}</div>
+        <div v-if="r.when_to_apply || r.updated_at" class="meta">
+          <span v-if="r.when_to_apply" class="trigger">{{ r.when_to_apply }}</span>
+          <span v-if="r.updated_at" class="age" :title="`Last changed ${r.updated_at}`">{{ r.updated_at }}</span>
+        </div>
       </li>
     </ul>
     <button class="new-rule" @click="emit('create-rule', topicId)">+ New rule</button>
@@ -35,5 +44,19 @@ li {
 li:hover { background: var(--fs-surface-hover); }
 .title { font-family: Fraunces, serif; font-style: italic; font-size: 1.05em; }
 .statement { font-size: 0.9em; opacity: 0.8; margin-top: 0.25rem; }
+.meta { display: flex; align-items: baseline; gap: 0.5rem; margin-top: 0.35rem; font-size: 0.75em; }
+.trigger { flex: 1; min-width: 0; color: var(--fs-text-secondary); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.age { color: var(--fs-text-tertiary); font-variant-numeric: tabular-nums; flex-shrink: 0; }
+.tier-chip {
+  margin-left: 0.4rem;
+  font-family: var(--fs-font-body);
+  font-style: normal;
+  font-size: 0.62rem;
+  color: var(--fs-text-secondary);
+  background: var(--fs-surface-raised);
+  border-radius: var(--fs-radius-pill);
+  padding: 0.05rem 0.4rem;
+  vertical-align: middle;
+}
 .new-rule { cursor: pointer; }
 </style>

frontend/src/stores/canonicalSystems.ts

@@ -0,0 +1,93 @@
+import { ref } from "vue";
+import { defineStore } from "pinia";
+import * as api from "@/api/canonicalSystems";
+import type { CanonicalSystem, MappingProposal } from "@/api/canonicalSystems";
+import { useToastStore } from "@/stores/toast";
+import { apiErrorMessage } from "@/api/client";
+
+/**
+ * The global area catalog (milestone 307). Shared by every project, so it is
+ * fetched ONCE per session rather than per project — the whole point of the
+ * table is that it is the same list everywhere.
+ */
+export const useCanonicalSystemsStore = defineStore("canonicalSystems", () => {
+  const catalog = ref<CanonicalSystem[]>([]);
+  const loaded = ref(false);
+  const loading = ref(false);
+  const proposalsByProject = ref<Record<number, MappingProposal[]>>({});
+
+  async function fetchCatalog(force = false) {
+    if (loaded.value && !force) return catalog.value;
+    loading.value = true;
+    try {
+      catalog.value = await api.listCanonicalSystems();
+      loaded.value = true;
+    } catch {
+      // A naming aid must never break the screen it rides on — an empty
+      // catalog degrades the suggestion, it does not fail the form.
+      catalog.value = [];
+    } finally {
+      loading.value = false;
+    }
+    return catalog.value;
+  }
+
+  function byId(id: number | null): CanonicalSystem | undefined {
+    if (id == null) return undefined;
+    return catalog.value.find((c) => c.id === id);
+  }
+
+  async function fetchProposals(projectId: number) {
+    proposalsByProject.value[projectId] = await api.proposeMappings(projectId);
+    return proposalsByProject.value[projectId];
+  }
+
+  /** Apply or clear one mapping, then drop it from the pending proposals. */
+  async function mapSystem(projectId: number, systemId: number, canonicalId: number | null) {
+    try {
+      await api.mapSystem(systemId, canonicalId);
+    } catch (e) {
+      useToastStore().show(apiErrorMessage(e, "Failed to map system"), "error");
+      throw e;
+    }
+    dismissProposal(projectId, systemId);
+  }
+
+  /** Remove a proposal from the pending list without writing anything. */
+  function dismissProposal(projectId: number, systemId: number) {
+    const list = proposalsByProject.value[projectId];
+    if (list) {
+      proposalsByProject.value[projectId] = list.filter((p) => p.system_id !== systemId);
+    }
+  }
+
+  async function createEntry(data: { name: string; description?: string }) {
+    const entry = await api.createCanonicalSystem(data);
+    catalog.value.push(entry);
+    return entry;
+  }
+
+  async function updateEntry(
+    id: number,
+    data: Partial<{ name: string; description: string; order_index: number }>,
+  ) {
+    const entry = await api.updateCanonicalSystem(id, data);
+    const idx = catalog.value.findIndex((c) => c.id === id);
+    if (idx >= 0) catalog.value[idx] = entry;
+    return entry;
+  }
+
+  return {
+    catalog,
+    loaded,
+    loading,
+    proposalsByProject,
+    fetchCatalog,
+    byId,
+    fetchProposals,
+    mapSystem,
+    dismissProposal,
+    createEntry,
+    updateEntry,
+  };
+});

frontend/src/stores/rulebooks.ts

@@ -35,9 +35,7 @@ export const useRulebooksStore = defineStore("rulebooks", () => {
   async function fetchRules(topicId: number) {
     try {
       const rules = await api.listRules({ topic_id: topicId });
-      rulesByTopic.value[topicId] = rules.map((r) => ({
-        id: r.id, title: r.title, statement: r.statement, topic_id: r.topic_id,
-      }));
+      rulesByTopic.value[topicId] = rules.map(toHeader);
     } catch (e) {
       useToastStore().show("Failed to load rules", "error");
       throw e;
@@ -98,24 +96,58 @@ export const useRulebooksStore = defineStore("rulebooks", () => {
     delete rulesByTopic.value[id];
   }
 
-  async function createRule(topicId: number, data: { title: string; statement: string; why?: string; how_to_apply?: string }) {
+  /**
+   * A list row built from a full rule. The row shape is the server's
+   * rule_brief, so every field it carries has to be mirrored here or the two
+   * disagree the moment a list is patched locally instead of re-fetched.
+   */
+  function toHeader(rule: Rule): api.RuleHeader {
+    return {
+      id: rule.id,
+      title: rule.title,
+      statement: rule.statement,
+      topic_id: rule.topic_id,
+      tier: rule.tier,
+      updated_at: rule.updated_at,
+      when_to_apply: rule.when_to_apply || undefined,
+      arose_from_id: rule.arose_from_id ?? undefined,
+    };
+  }
+
+  async function createRule(topicId: number, data: Partial<api.RuleWrite> & { title: string; statement: string }) {
     const rule = await api.createRule(topicId, data);
     if (!rulesByTopic.value[topicId]) rulesByTopic.value[topicId] = [];
-    rulesByTopic.value[topicId].push({ id: rule.id, title: rule.title, statement: rule.statement, topic_id: rule.topic_id });
+    rulesByTopic.value[topicId].push(toHeader(rule));
     return rule;
   }
 
-  async function updateRule(id: number, data: Partial<Pick<Rule, "title" | "statement" | "why" | "how_to_apply" | "order_index">>) {
+  async function updateRule(id: number, data: Partial<api.RuleWrite>) {
     const rule = await api.updateRule(id, data);
     if (currentRule.value?.id === id) currentRule.value = rule;
     for (const tid of Object.keys(rulesByTopic.value)) {
       const list = rulesByTopic.value[Number(tid)];
       const idx = list.findIndex((r) => r.id === id);
-      if (idx >= 0) list[idx] = { id: rule.id, title: rule.title, statement: rule.statement, topic_id: rule.topic_id };
+      if (idx >= 0) list[idx] = toHeader(rule);
     }
     return rule;
   }
 
+  async function relateRules(
+    fromRuleId: number,
+    data: { to_rule_id: number; kind: api.RuleRelationKind; note?: string },
+  ) {
+    await api.relateRules(fromRuleId, data);
+    // Re-read rather than patching locally: the edge reads from BOTH ends, so
+    // the far rule's relations changed too and a local splice would show only
+    // half of what just happened.
+    await fetchRule(fromRuleId);
+  }
+
+  async function unrelateRules(relationId: number, refreshRuleId: number) {
+    await api.unrelateRules(relationId);
+    await fetchRule(refreshRuleId);
+  }
+
   async function deleteRule(id: number) {
     await api.deleteRule(id);
     if (currentRule.value?.id === id) currentRule.value = null;
@@ -129,6 +161,6 @@ export const useRulebooksStore = defineStore("rulebooks", () => {
     fetchRulebooks, fetchTopics, fetchRules, fetchRule,
     createRulebook, updateRulebook, toggleAlwaysOn, deleteRulebook,
     createTopic, updateTopic, deleteTopic,
-    createRule, updateRule, deleteRule,
+    createRule, updateRule, deleteRule, relateRules, unrelateRules,
   };
 });

frontend/src/stores/systems.ts

@@ -22,7 +22,7 @@ export const useSystemsStore = defineStore("systems", () => {
 
   async function createSystem(
     projectId: number,
-    data: { name: string; description?: string; color?: string },
+    data: { name: string; description?: string; color?: string; canonical_id?: number },
   ) {
     const system = await api.createSystem(projectId, data);
     if (!systemsByProject.value[projectId]) systemsByProject.value[projectId] = [];

frontend/src/views/SettingsView.vue

@@ -3,6 +3,7 @@ import { ref, computed, watch, onMounted } from "vue";
 import { useSettingsStore } from "@/stores/settings";
 import { useAuthStore } from "@/stores/auth";
 import { useToastStore } from "@/stores/toast";
+import { useCanonicalSystemsStore } from "@/stores/canonicalSystems";
 import { apiGet, apiPost, apiPut, apiDelete, listGroups, createGroup, deleteGroup, listGroupMembers, addGroupMember, removeGroupMember, searchUsers, listApiKeys, createApiKey as apiCreateApiKey, revokeApiKey as apiRevokeApiKey, getProfile, updateProfile, type ApiKeyEntry, type GroupEntry, type GroupMember, type UserSearchResult, type UserProfile, apiErrorMessage } from "@/api/client";
 import type { User } from "@/types/auth";
 import PaginationBar from "@/components/PaginationBar.vue";
@@ -12,6 +13,62 @@ import { fmtDate, fmtLogStamp } from "@/utils/dateFormat";
 const store = useSettingsStore();
 const authStore = useAuthStore();
 const toastStore = useToastStore();
+
+// ── Shared areas (milestone 307) ────────────────────────────────────────
+// The global vocabulary a project's Systems map onto. Admin-only to WRITE —
+// a global list anyone can extend stops being a shared list — but every user
+// reads it, which is why the catalog lives in a store rather than here.
+const canonStore = useCanonicalSystemsStore();
+const newAreaName = ref("");
+const newAreaDescription = ref("");
+const creatingArea = ref(false);
+const editingAreaId = ref<number | null>(null);
+const editAreaName = ref("");
+const editAreaDescription = ref("");
+const savingArea = ref(false);
+
+async function createArea() {
+  const name = newAreaName.value.trim();
+  if (!name || creatingArea.value) return;
+  creatingArea.value = true;
+  try {
+    await canonStore.createEntry({
+      name,
+      description: newAreaDescription.value.trim() || undefined,
+    });
+    newAreaName.value = "";
+    newAreaDescription.value = "";
+    toastStore.show("Area added");
+  } catch (e) {
+    // A 409 means an area with the same match key already exists — say which,
+    // because "CI and Release" vs "CI & Release" looks like a different name.
+    toastStore.show(apiErrorMessage(e, "Failed to add area"), "error");
+  } finally {
+    creatingArea.value = false;
+  }
+}
+
+function startEditArea(id: number, name: string, description: string | null) {
+  editingAreaId.value = id;
+  editAreaName.value = name;
+  editAreaDescription.value = description ?? "";
+}
+
+async function saveArea() {
+  const id = editingAreaId.value;
+  const name = editAreaName.value.trim();
+  if (id == null || !name || savingArea.value) return;
+  savingArea.value = true;
+  try {
+    await canonStore.updateEntry(id, { name, description: editAreaDescription.value.trim() });
+    editingAreaId.value = null;
+    toastStore.show("Area updated");
+  } catch (e) {
+    toastStore.show(apiErrorMessage(e, "Failed to update area"), "error");
+  } finally {
+    savingArea.value = false;
+  }
+}
 const userTimezone = ref("");
 const savingTimezone = ref(false);
 const timezoneSaved = ref(false);
@@ -134,7 +191,7 @@ const appVersion = ref('dev');
 const restoreFileInput = ref<HTMLInputElement | null>(null);
 
 // Migrate stored "admin" → "config"; unknown tabs fall back to "general"
-const VALID_TABS = new Set(["general", "account", "profile", "notifications", "integrations", "data", "apikeys", "config", "users", "logs", "groups"]);
+const VALID_TABS = new Set(["general", "account", "profile", "notifications", "integrations", "data", "apikeys", "config", "users", "logs", "groups", "areas"]);
 const _stored = localStorage.getItem("settings_tab") ?? "general";
 const activeTab = ref(VALID_TABS.has(_stored) ? (_stored === "admin" ? "config" : _stored) : "general");
 
@@ -143,6 +200,7 @@ function _loadTabContent(tab: string) {
     if (tab === "users") loadUsersPanel();
     else if (tab === "logs") loadLogsPanel();
     else if (tab === "groups") loadGroupsPanel();
+    else if (tab === "areas") canonStore.fetchCatalog(true);
   }
   if (tab === "apikeys") { fetchApiKeys(); }
 }
@@ -1212,7 +1270,7 @@ async function deleteUser(userId: number) {
       <div v-if="authStore.isAdmin" class="sidebar-group">
         <div class="sidebar-group-label">Admin</div>
         <button
-          v-for="tab in ['config', 'users', 'groups', 'logs']"
+          v-for="tab in ['config', 'areas', 'users', 'groups', 'logs']"
           :key="tab"
           :class="['sidebar-item', { active: activeTab === tab }]"
           @click="activeTab = tab"
@@ -2263,6 +2321,78 @@ async function deleteUser(userId: number) {
     </div>
 
     <!-- ── Users ── -->
+    <!-- ── Shared areas ── -->
+    <div v-if="authStore.isAdmin" v-show="activeTab === 'areas'" class="settings-grid">
+      <section class="settings-section full-width">
+        <h2>Shared areas</h2>
+        <p class="field-hint">
+          The vocabulary every project's Systems can be filed under, so the same word means the
+          same thing everywhere. A project keeps its own name for an area — mapping records which
+          shared area it is, it never renames anything. Editing a name here re-derives its match
+          key, so existing mappings are kept but future name matching follows the new spelling.
+        </p>
+
+        <ul class="area-admin-list">
+          <li v-for="entry in canonStore.catalog" :key="entry.id" class="area-admin-row">
+            <template v-if="editingAreaId === entry.id">
+              <form class="area-admin-form" @submit.prevent="saveArea">
+                <input v-model="editAreaName" class="fs-input" aria-label="Area name" />
+                <textarea
+                  v-model="editAreaDescription"
+                  class="fs-input"
+                  rows="2"
+                  aria-label="Area description"
+                ></textarea>
+                <div class="area-admin-actions">
+                  <button type="submit" class="btn-primary btn-compact" :disabled="!editAreaName.trim() || savingArea">
+                    {{ savingArea ? "Saving…" : "Save" }}
+                  </button>
+                  <button type="button" class="btn-ghost btn-compact" @click="editingAreaId = null">Cancel</button>
+                </div>
+              </form>
+            </template>
+            <template v-else>
+              <div class="area-admin-body">
+                <div class="area-admin-name-row">
+                  <span class="area-admin-name">{{ entry.name }}</span>
+                  <code class="area-admin-slug" title="The match key. Names that reduce to this are the same area.">{{ entry.slug }}</code>
+                </div>
+                <p v-if="entry.description" class="area-admin-desc">{{ entry.description }}</p>
+              </div>
+              <button
+                class="btn-ghost btn-compact"
+                @click="startEditArea(entry.id, entry.name, entry.description)"
+              >Edit</button>
+            </template>
+          </li>
+        </ul>
+        <p v-if="!canonStore.catalog.length && !canonStore.loading" class="settings-empty">
+          No areas yet.
+        </p>
+
+        <form class="area-admin-form area-admin-create" @submit.prevent="createArea">
+          <input
+            v-model="newAreaName"
+            class="fs-input"
+            placeholder="New area name (e.g. Search &amp; Indexing)"
+            aria-label="New area name"
+          />
+          <textarea
+            v-model="newAreaDescription"
+            class="fs-input"
+            rows="2"
+            placeholder="What belongs in this area? One paragraph — a bare name is never enough."
+            aria-label="New area description"
+          ></textarea>
+          <div class="area-admin-actions">
+            <button type="submit" class="btn-primary btn-compact" :disabled="!newAreaName.trim() || creatingArea">
+              {{ creatingArea ? "Adding…" : "Add area" }}
+            </button>
+          </div>
+        </form>
+      </section>
+    </div>
+
     <div v-if="authStore.isAdmin" v-show="activeTab === 'users'" class="settings-grid">
 
       <section class="settings-section full-width">
@@ -3401,4 +3531,34 @@ async function deleteUser(userId: number) {
   color: var(--fs-accent);
   font-weight: 500;
 }
+
+/* ── Shared areas (milestone 307) ──────────────────────────────────
+   The slug is shown deliberately: it is what decides whether two names are
+   the same area, and an admin renaming an entry needs to see it move. */
+.area-admin-list { list-style: none; margin: 1rem 0 0; padding: 0; display: flex; flex-direction: column; gap: var(--fs-space-2); }
+.area-admin-row {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--fs-space-3);
+  padding: var(--fs-space-3);
+  background: var(--fs-surface-raised);
+  border: 1px solid var(--fs-border-color);
+  border-radius: var(--fs-radius-md);
+}
+.area-admin-body { flex: 1; min-width: 0; }
+.area-admin-name-row { display: flex; align-items: baseline; gap: var(--fs-space-2); flex-wrap: wrap; }
+.area-admin-name { color: var(--fs-text-primary); }
+.area-admin-slug {
+  font-family: var(--fs-font-mono);
+  font-size: 0.72rem;
+  color: var(--fs-text-tertiary);
+  background: var(--fs-surface-code-inline);
+  border-radius: var(--fs-radius-sm);
+  padding: 0.05rem 0.35rem;
+}
+.area-admin-desc { margin: 0.35rem 0 0; font-size: 0.85rem; color: var(--fs-text-secondary); }
+.area-admin-form { display: flex; flex-direction: column; gap: 0.5rem; flex: 1; }
+.area-admin-create { margin-top: var(--fs-space-4); }
+.area-admin-actions { display: flex; gap: 0.4rem; }
 </style>

plugin/.claude-plugin/plugin.json

@@ -1,13 +1,17 @@
 {
   "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.46",
-  "author": { "name": "Bryan Van Deusen" },
+  "version": "0.1.47",
+  "author": {
+    "name": "Bryan Van Deusen"
+  },
   "mcpServers": {
     "scribe": {
       "type": "http",
       "url": "${user_config.api_endpoint}/mcp",
-      "headers": { "Authorization": "Bearer ${user_config.api_token}" }
+      "headers": {
+        "Authorization": "Bearer ${user_config.api_token}"
+      }
     }
   },
   "userConfig": {
@@ -19,7 +23,7 @@
     "api_token": {
       "type": "string",
       "title": "Scribe API key",
-      "description": "An fmcp_ API key from Settings → API Keys (read scope is enough for the session-start hook; write scope to use the tools)",
+      "description": "An fmcp_ API key from Settings \u2192 API Keys (read scope is enough for the session-start hook; write scope to use the tools)",
       "sensitive": true
     }
   }

plugin/hooks/scribe_prior_art.sh

@@ -174,17 +174,24 @@ mkdir -p "$state_dir" 2>/dev/null || true
 # (a derive group id) or a canon elsewhere (`canon:<snippet_id>`) for the
 # shapes being written. Keyed by that token, not a note id, so it dedups on
 # its own file and a family is named once per session, not at every edit.
+#
+# A FOURTH channel (milestone 307): standing RULES the write resembles. Its own
+# file for the same reason as the others — a rule named once should not be
+# re-offered on every subsequent write in the session.
 idfile=""
 syncfile=""
 derivefile=""
+rulefile=""
 exclude_q=""
 sync_exclude_q=""
 derive_exclude_q=""
+rule_exclude_q=""
 if [ -n "$session_id" ]; then
   safe_sid=$(printf '%s' "$session_id" | tr -c 'A-Za-z0-9._-' '_')
   idfile="$state_dir/${safe_sid}.ids"
   syncfile="$state_dir/${safe_sid}.sync.ids"
   derivefile="$state_dir/${safe_sid}.derive.ids"
+  rulefile="$state_dir/${safe_sid}.rules.ids"
   if [ -f "$idfile" ]; then
     seen=$(tr '\n' ',' < "$idfile" 2>/dev/null | sed 's/,$//')
     [ -n "$seen" ] && exclude_q="&exclude_ids=${seen}"
@@ -197,6 +204,10 @@ if [ -n "$session_id" ]; then
     derive_seen=$(tr '\n' ',' < "$derivefile" 2>/dev/null | sed 's/,$//' | jq -sRr '@uri' 2>/dev/null) || derive_seen=""
     [ -n "$derive_seen" ] && derive_exclude_q="&exclude_derive=${derive_seen}"
   fi
+  if [ -f "$rulefile" ]; then
+    rule_seen=$(tr '\n' ',' < "$rulefile" 2>/dev/null | sed 's/,$//')
+    [ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}"
+  fi
 fi
 
 # Not `|| exit 0`: an unreachable instance must not discard a local finding
@@ -206,7 +217,7 @@ fi
 reached=1
 body=$(curl -fsS --max-time 5 \
   -H "Authorization: Bearer ${token}" \
-  "${url%/}/api/plugin/prior-art?path=${path_enc}&code=${code_enc}${repo_q}${exclude_q}${sync_exclude_q}${derive_exclude_q}${shapes_q}" 2>/dev/null) || { body=""; reached=0; }
+  "${url%/}/api/plugin/prior-art?path=${path_enc}&code=${code_enc}${repo_q}${exclude_q}${sync_exclude_q}${derive_exclude_q}${rule_exclude_q}${shapes_q}" 2>/dev/null) || { body=""; reached=0; }
 unreached_context=""
 if [ "$reached" = 1 ]; then
   scribe_reached "$state_dir" "${safe_sid:-nosession}"
@@ -227,6 +238,9 @@ if [ -n "$body" ]; then
     if [ -n "$syncfile" ]; then
       printf '%s' "$body" | jq -r '(.sync_note_ids // [])[]?' 2>/dev/null >> "$syncfile" || true
     fi
+    if [ -n "$rulefile" ]; then
+      printf '%s' "$body" | jq -r '(.rule_ids // [])[]?' 2>/dev/null >> "$rulefile" || true
+    fi
     if [ -n "$derivefile" ]; then
       printf '%s' "$body" | jq -r '(.derive_keys // [])[]?' 2>/dev/null >> "$derivefile" || true
     fi

src/scribe/app.py

@@ -30,6 +30,7 @@ from scribe.routes.design_systems import design_systems_bp
 from scribe.routes.trash import trash_bp
 from scribe.routes.dashboard import dashboard_bp
 from scribe.routes.systems import systems_bp
+from scribe.routes.canonical_systems import canonical_systems_bp
 from scribe.routes.snippets import snippets_bp
 from scribe.routes.webhooks import webhooks_bp
 from scribe.mcp import mount_mcp
@@ -95,6 +96,7 @@ def create_app() -> Quart:
     app.register_blueprint(trash_bp)
     app.register_blueprint(dashboard_bp)
     app.register_blueprint(systems_bp)
+    app.register_blueprint(canonical_systems_bp)
     app.register_blueprint(snippets_bp)
     app.register_blueprint(webhooks_bp)
 
@@ -159,7 +161,7 @@ def create_app() -> Quart:
         import asyncio
 
         from scribe.services.auth import start_auth_token_retention_loop
-        from scribe.services.embeddings import backfill_note_embeddings
+        from scribe.services.embeddings import backfill_note_embeddings, backfill_rule_embeddings
         from scribe.services.logging import start_log_retention_loop
         from scribe.services.notifications import start_notification_loop
 
@@ -174,6 +176,12 @@ def create_app() -> Quart:
                 await backfill_note_embeddings()
             except Exception:
                 logger.warning("Embedding backfill failed", exc_info=True)
+            # Rules got vectors in milestone 307; every rule written before it
+            # has none, so this is the pass that makes them findable at all.
+            try:
+                await backfill_rule_embeddings()
+            except Exception:
+                logger.warning("Rule embedding backfill failed", exc_info=True)
             # Snippets written before migration 0070 have no `notes.data` mirror,
             # and the location reverse lookup queries that column — an unfilled
             # row would read as "no snippet here" rather than as a gap. Separate

src/scribe/mcp/server.py

@@ -91,6 +91,9 @@ _READ_ONLY_TOOLS = frozenset({
     "list_rules", "list_tags", "list_tasks", "list_topics", "list_trash",
     "list_always_on_rules", "search",
     "get_system", "list_systems", "list_system_records",
+    # The global area catalog and its mapping REPORT — propose writes nothing;
+    # map_system_to_canonical is the separate, explicitly-called write.
+    "list_canonical_systems", "propose_canonical_mappings",
     # Reports on the corpus. Reads only — the merge or supersession each
     # suggests is a separate, explicitly-called write.
     "find_duplicate_snippets", "find_duplicate_records",

src/scribe/mcp/tools/rulebooks.py

@@ -1,7 +1,12 @@
 """MCP tools for the Scribe Rulebook system.
 
-Sixteen tools: rulebook/topic/rule CRUD + subscription management. Thin
-wrappers over services/rulebooks.py — ownership is enforced in the service.
+Rulebook / topic / rule CRUD, subscription management, and the rule-to-rule
+edges. Thin wrappers over services/rulebooks.py — ownership is enforced in the
+service, and the record shape comes from rule_brief / rule_detail there rather
+than being rebuilt here.
+
+(The header used to say "Sixteen tools" and had been wrong for two milestones;
+the count lives in the registration test, which fails when it drifts.)
 
 Destructive ops (delete_*) require confirmed=True; otherwise return a
 preview-style warning. Mirrors the pattern in delete_event and the design
@@ -195,8 +200,12 @@ async def delete_topic(topic_id: int, confirmed: bool = False) -> dict:
 
 def _rule_summary(r) -> dict:
     """The list-row shape for a rule: what an agent needs to APPLY it. The
-    full record (why, how_to_apply, timestamps) is get_rule's job."""
-    return {"id": r.id, "title": r.title, "statement": r.statement, "topic_id": r.topic_id}
+    full record (why, how_to_apply, timestamps) is get_rule's job.
+
+    One line, because the shape itself lives in the service — this was one of
+    three hand-written copies that had already drifted apart (note 3026).
+    """
+    return rulebooks_svc.rule_brief(r)
 
 
 async def list_rules(
@@ -227,6 +236,13 @@ async def list_always_on_rules(project_id: int = 0) -> dict:
 
     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.
+
+    Returns the ALWAYS-ON tier only (milestone 307). A `conditional` rule is
+    still binding when it applies; it just is not resident — it reaches a
+    session through enter_project (when the project works in an area the rule
+    is tagged to) or through search(content_type="rule"). Nothing here is a
+    behaviour change until rules are actually re-tiered: `tier` defaults to
+    always_on, so an existing rulebook returns exactly what it always did.
     Pair with get_project(id).applicable_rules when working on a specific
     project to also load that project's subscription-derived rules.
 
@@ -242,18 +258,25 @@ async def list_always_on_rules(project_id: int = 0) -> dict:
 
 
 async def get_rule(rule_id: int) -> dict:
-    """Fetch a rule by id — full statement + why + how_to_apply."""
+    """Fetch a rule by id — full statement + why + how_to_apply.
+
+    Also carries what a listing leaves out: the global `systems` this rule is
+    about, and its `relations`. Read the relations before acting on the rule —
+    a rule with a `co_surfaces` edge is half of a shape, and an `overrides`
+    edge means one of the pair is not in force here.
+    """
     uid = current_user_id()
     rule = await rulebooks_svc.get_rule(rule_id, uid)
     if rule is None:
         raise ValueError(f"rule {rule_id} not found")
-    return rule.to_dict()
+    return await rulebooks_svc.rule_detail(uid, rule)
 
 
 async def create_rule(
-    topic_id: int, title: str, statement: str,
+    topic_id: int, title: str, statement: str, when_to_apply: str = "",
     why: str = "", how_to_apply: str = "", order_index: int = 0,
-    force: bool = False,
+    tier: str = "always_on", system_ids: list[int] | None = None,
+    arose_from_id: int = 0, force: bool = False,
 ) -> dict:
     """Create a new rule in a rulebook (a SHARED rule — keep it general).
 
@@ -273,10 +296,36 @@ async def create_rule(
     Reusable code is a SNIPPET. Reach for a rule only when the thing genuinely
     is a standing instruction about how to work and nothing else can hold it.
 
+    ONE RULE = ONE THING YOU COULD VIOLATE. If a clause can be broken on its
+    own, and fixing that breakage doesn't require the neighbouring clauses, it
+    is a separate rule. Rules that FAIL TOGETHER get linked with relate_rules
+    (kind="co_surfaces"), never merged into one row: a merged rule cannot be
+    cited, surfaced or suppressed a clause at a time, and it grows without
+    limit because adding to it is always cheaper than adding a rule.
+
     Args:
         topic_id: The topic to attach the rule to.
         title: A short imperative title (e.g. "dev is home").
         statement: The actionable instruction (required). 1-2 sentences.
+        when_to_apply: WHEN this rule fires — the trigger, not the
+            instruction. State the moment or the material: "before any git
+            push", "when adding a value to a CHECK-gated column", "when a
+            release is being cut". Write it even though the parameter is
+            optional: it decides the tier below, it is how the rule is found
+            when it matters, and a rule nobody can place is a rule nobody
+            applies.
+        tier: "always_on" (default) or "conditional".
+            The test: can you name the trigger WITHOUT naming a system, an
+            artifact type or a moment? If the honest answer is "whenever you
+            are working", it is always_on. If you had to name something, it is
+            conditional — and conditional costs nothing when it is irrelevant,
+            which is what lets it be as long as it needs to be.
+        system_ids: Ids from list_canonical_systems — the global AREAS this
+            rule is about. This is what lets a rule reach a project that is
+            working in that area, so a CI rule surfaces on a CI change.
+        arose_from_id: The note or task that CAUSED this rule (an incident, a
+            decision). Prefer this over naming the record inside `why`, which
+            cannot be followed and does not survive a rewording.
         why: Optional rationale — the reason the rule exists.
         how_to_apply: Optional operationalization — when / where it kicks in.
         order_index: Display order within the topic (default 0).
@@ -291,16 +340,18 @@ async def create_rule(
             return dedup_svc.duplicate_response(dup, "rule")
     rule = await rulebooks_svc.create_rule(
         topic_id=topic_id, user_id=uid,
-        title=title, statement=statement,
+        title=title, statement=statement, when_to_apply=when_to_apply,
+        tier=tier, arose_from_id=arose_from_id,
         why=why, how_to_apply=how_to_apply, order_index=order_index,
     )
-    return rule.to_dict()
+    return await rulebooks_svc.rule_detail(uid, rule, system_ids)
 
 
 async def create_project_rule(
-    project_id: int, statement: str, title: str = "",
+    project_id: int, statement: str, title: str = "", when_to_apply: str = "",
     why: str = "", how_to_apply: str = "", order_index: int = 0,
-    force: bool = False,
+    tier: str = "always_on", system_ids: list[int] | None = None,
+    arose_from_id: int = 0, force: bool = False,
 ) -> dict:
     """Create a rule scoped to a single project (no rulebook needed).
 
@@ -312,11 +363,24 @@ async def create_project_rule(
     the rule is returned in get_project's applicable_rules (under
     project_rules) and in list_rules(project_id=...).
 
+    ONE RULE = ONE THING YOU COULD VIOLATE — see create_rule. A rule that
+    STRICTENS or REPLACES an inherited one is not a fresh rule: write it, then
+    relate_rules(kind="overrides") to the rule it supersedes, so the pair stays
+    connected instead of drifting into a contradiction nobody notices. A rule
+    that merely adds local detail to an inherited one uses "elaborates".
+
     Args:
         project_id: The project to attach the rule to.
         statement: The actionable instruction (required). 1-2 sentences.
         title: Short imperative title. If empty, derived from the first ~50
             characters of statement.
+        when_to_apply: WHEN this rule fires — the trigger, not the
+            instruction. See create_rule; it decides the tier and it is how
+            the rule is found at the moment it matters.
+        tier: "always_on" (default) or "conditional" — see create_rule.
+        system_ids: Ids from list_canonical_systems — the global AREAS this
+            rule is about.
+        arose_from_id: The note or task that CAUSED this rule.
         why: Optional rationale — the reason the rule exists.
         how_to_apply: Optional operationalization — when / where it kicks in.
         order_index: Display order within the project's rule list (default 0).
@@ -332,23 +396,36 @@ async def create_project_rule(
             return dedup_svc.duplicate_response(dup, "rule")
     rule = await rulebooks_svc.create_project_rule(
         project_id=project_id, user_id=uid,
-        title=derived_title, statement=statement,
+        title=derived_title, statement=statement, when_to_apply=when_to_apply,
+        tier=tier, arose_from_id=arose_from_id,
         why=why, how_to_apply=how_to_apply, order_index=order_index,
     )
-    return rule.to_dict()
+    return await rulebooks_svc.rule_detail(uid, rule, system_ids)
 
 
 async def update_rule(
-    rule_id: int, title: str = "", statement: str = "",
+    rule_id: int, title: str = "", statement: str = "", when_to_apply: str = "",
     why: str = "", how_to_apply: str = "", order_index: int = -1,
+    tier: str = "", system_ids: list[int] | None = None, arose_from_id: int = 0,
 ) -> dict:
-    """Update a rule. Empty strings / order_index=-1 leave fields unchanged."""
+    """Update a rule. Empty strings / order_index=-1 leave fields unchanged.
+
+    Adding `when_to_apply` and a `tier` to an existing rule is the ordinary way
+    a rule stops being preloaded into every session and starts arriving when it
+    is relevant. `system_ids` REPLACES the rule's areas (pass [] to clear).
+    """
     uid = current_user_id()
     fields: dict = {}
     if title:
         fields["title"] = title
     if statement:
         fields["statement"] = statement
+    if when_to_apply:
+        fields["when_to_apply"] = when_to_apply
+    if tier:
+        fields["tier"] = tier
+    if arose_from_id:
+        fields["arose_from_id"] = arose_from_id
     if why:
         fields["why"] = why
     if how_to_apply:
@@ -358,7 +435,7 @@ async def update_rule(
     rule = await rulebooks_svc.update_rule(rule_id, uid, **fields)
     if rule is None:
         raise ValueError(f"rule {rule_id} not found")
-    return rule.to_dict()
+    return await rulebooks_svc.rule_detail(uid, rule, system_ids)
 
 
 async def delete_rule(rule_id: int, confirmed: bool = False) -> dict:
@@ -496,12 +573,59 @@ async def unsuppress_topic_for_project(
     return {"project_id": project_id, "topic_id": topic_id, "suppressed": False}
 
 
+
+
+async def relate_rules(
+    from_rule_id: int, to_rule_id: int, kind: str, note: str = "",
+) -> dict:
+    """Draw a typed edge between two rules. Both must be yours.
+
+    Reach for this INSTEAD of merging or duplicating:
+
+    - kind="co_surfaces" — these two fail together, so they must arrive
+      together. Use it when you are tempted to fold one rule into another
+      because "either could surface without the other": that instinct is
+      right and merging is the wrong fix, because a merged rule cannot be
+      cited, suppressed or surfaced a clause at a time. Symmetric — draw it
+      once, it reads from both ends.
+    - kind="overrides" — this rule supersedes that one for its scope. Use it
+      when a project rule is stricter than, or replaces, an inherited one,
+      instead of writing a near-copy that will drift from its parent.
+    - kind="elaborates" — this rule adds local specifics to that one, and
+      should arrive with it rather than instead of it.
+
+    Idempotent: re-drawing an existing edge returns it.
+
+    Args:
+        note: WHY the edge holds. Worth writing for the same reason a rule
+            carries `why` — a later reader deciding whether it still applies
+            needs the reasoning, not just the fact.
+    """
+    uid = current_user_id()
+    relation = await rulebooks_svc.add_rule_relation(
+        uid, from_rule_id, to_rule_id, kind, note,
+    )
+    if relation is None:
+        raise ValueError(
+            f"rule {from_rule_id} or {to_rule_id} not found (both must be yours)"
+        )
+    return relation.to_dict()
+
+
+async def unrelate_rules(relation_id: int) -> dict:
+    """Remove one edge between rules (from relate_rules / get_rule.relations)."""
+    uid = current_user_id()
+    if not await rulebooks_svc.remove_rule_relation(uid, relation_id):
+        raise ValueError(f"relation {relation_id} not found")
+    return {"deleted": relation_id}
+
 def register(mcp) -> None:
     for fn in (
         list_rulebooks, get_rulebook, create_rulebook, update_rulebook, delete_rulebook,
         list_topics, create_topic, update_topic, delete_topic,
         list_rules, list_always_on_rules, get_rule,
         create_rule, create_project_rule, update_rule, delete_rule,
+        relate_rules, unrelate_rules,
         subscribe_project_to_rulebook, unsubscribe_project_from_rulebook,
         suppress_rule_for_project, unsuppress_rule_for_project,
         suppress_topic_for_project, unsuppress_topic_for_project,

src/scribe/mcp/tools/search.py

@@ -11,10 +11,44 @@ import time
 
 from scribe.mcp._context import current_user_id
 from scribe.services.access import owner_names_for
-from scribe.services.embeddings import DEFAULT_SIMILARITY_THRESHOLD, semantic_search_notes
+from scribe.services.embeddings import (
+    DEFAULT_SIMILARITY_THRESHOLD, semantic_search_notes, semantic_search_rules,
+)
 from scribe.services.retrieval_telemetry import record_retrieval, retrieval_summary
 
 
+async def _search_rules(uid: int, q: str, limit: int) -> dict:
+    """Rules by meaning — a separate result shape because a rule IS different.
+
+    A rule hit carries `why` and `how_to_apply`: they are the operational half
+    of a rule and the session-start payload never includes them, so a caller
+    who went looking should get the whole thing rather than a summary they then
+    have to re-fetch.
+
+    Rules are not project-scoped the way notes are (a family rule belongs to no
+    project), so `project_id` and `system_id` do not apply here.
+    """
+    raw = await semantic_search_rules(uid, q, limit=limit)
+    return {
+        "results": [
+            {
+                "id": rule.id,
+                "title": rule.title,
+                "statement": rule.statement,
+                "when_to_apply": rule.when_to_apply or "",
+                "tier": rule.tier,
+                "why": rule.why or "",
+                "how_to_apply": rule.how_to_apply or "",
+                "topic_id": rule.topic_id,
+                "project_id": rule.project_id,
+                "similarity": float(score),
+            }
+            for score, rule in raw
+        ],
+        "total": len(raw),
+    }
+
+
 async def search(
     q: str,
     content_type: str = "all",
@@ -33,7 +67,13 @@ async def search(
 
     Args:
         q: search query string.
-        content_type: 'all' (default), 'note' (notes only), or 'task' (tasks only).
+        content_type: 'all' (default), 'note' (notes only), 'task' (tasks
+            only), or 'rule' (RULES only — the operator's standing
+            instructions, searchable by meaning since milestone 307).
+            Reach for 'rule' when you want to know whether a standing
+            instruction covers something: "is there a rule about release
+            tagging?". A hit carries the rule's `why` and `how_to_apply`,
+            which the session-start payload does not.
         limit: maximum number of results (1-50).
         project_id: Scope results to one project. PASS THE ACTIVE PROJECT'S ID
             whenever a project is in scope (the one you entered with
@@ -56,6 +96,8 @@ async def search(
     """
     uid = current_user_id()
     limit = max(1, min(limit, 50))
+    if content_type == "rule":
+        return await _search_rules(uid, q, limit)
     is_task = {"note": False, "task": True}.get(content_type)  # None => any
     t0 = time.perf_counter()
     raw = await semantic_search_notes(

src/scribe/mcp/tools/systems.py

@@ -13,6 +13,7 @@ Sentinels (match the milestone/task tool conventions):
 from __future__ import annotations
 
 from scribe.mcp._context import current_user_id
+from scribe.services import canonical_systems as canonical_systems_svc
 from scribe.services import notes as notes_svc
 from scribe.services import systems as systems_svc
 
@@ -30,10 +31,9 @@ _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.
-# 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)
+# The standard vocabulary lives in the GLOBAL canonical catalog since
+# milestone 307 — the inception seed mints it and this ask names it, one list
+# for both, now a table so a rule can reference an area by id (note 3026).
 
 
 async def bootstrap_systems_ask(user_id: int, project_id: int) -> str | None:
@@ -67,6 +67,17 @@ async def bootstrap_systems_ask(user_id: int, project_id: int) -> str | None:
     titles = "; ".join(
         '"' + " ".join((n.title or "").split())[:70] + '"' for n in recent
     )
+    try:
+        standard = ", ".join(name for name, _charter in await systems_svc.standard_systems())
+    except Exception:
+        standard = ""
+    # An install whose catalog is empty still gets a usable ask — the standard
+    # names are an aid, not the point of the question.
+    standard_line = (
+        "Where an area fits a standard name, use it verbatim so it means the "
+        f"same thing in every project: {standard}. Mint freely beyond that "
+        "list — the duplicate gate guards sprawl. "
+    ) if standard else "The duplicate gate guards sprawl. "
     return (
         f"This project has {total} records and NO Systems modelled — none of "
         "them can be tagged to an area, so recurring problem-spots stay "
@@ -74,10 +85,8 @@ async def bootstrap_systems_ask(user_id: int, project_id: int) -> str | None:
         "asking permission — creating Systems is your call, not an approval "
         f"flow. From the areas the records themselves name (recent: {titles}), "
         "create_system 3-6 Systems, each with a one-paragraph charter, then "
-        "tag this record (system_ids=[...]). Where an area fits a standard "
-        f"name, use it verbatim so it means the same thing in every project: "
-        f"{', '.join(_STANDARD_SYSTEMS)}. Mint freely beyond that list — the "
-        "duplicate gate guards sprawl. This ask repeats until the first "
+        f"tag this record (system_ids=[...]). {standard_line}"
+        "This ask repeats until the first "
         "System exists; answering it once retires it for every future record."
     )
 
@@ -188,36 +197,60 @@ async def create_system(
     normalized name already exists in this project (archived included), the
     call returns {"duplicate": true, "existing_id": ...} instead of creating —
     tag records to that one, or update_system it if its charter needs work.
+
+    Also mapped against the GLOBAL area catalog, so the same word means the
+    same thing in every project (milestone 307). A name that IS a catalog area
+    up to spelling ("CI and Release" vs "CI & Release") is mapped for you and
+    the response says so. A name that merely RESEMBLES one comes back with
+    `canonical_suggestion` — an offer, not a decision: apply it with
+    map_system_to_canonical if it really is that area, ignore it if this is a
+    project-specific area. Either way the System is created; the catalog never
+    blocks a name.
     """
     uid = current_user_id()
-    norm = " ".join(name.split()).lower()
-    if norm:
-        try:
-            existing = await systems_svc.list_systems(
-                uid, project_id, include_archived=True
-            )
-        except Exception:
-            existing = []
-        for s in existing:
-            if " ".join(s.name.split()).lower() == norm:
-                return {
-                    "duplicate": True,
-                    "existing_id": s.id,
-                    "message": (
-                        f"System '{s.name}' (#{s.id}) already covers this area "
-                        "in this project. Tag records to it with system_ids, "
-                        "or update_system it if the charter needs revising — "
-                        "a second System with the same name would split the "
-                        "area's records across two piles."
-                    ),
-                }
+    assessment = await systems_svc.assess_system_name(uid, project_id, name)
+    duplicate = assessment["duplicate"]
+    if duplicate:
+        return {
+            "duplicate": True,
+            "existing_id": duplicate["id"],
+            "message": (
+                f"System '{duplicate['name']}' (#{duplicate['id']}) already "
+                "covers this area in this project. Tag records to it with "
+                "system_ids, or update_system it if the charter needs "
+                "revising — a second System with the same name would split "
+                "the area's records across two piles."
+            ),
+        }
+    # An exact match is mechanical, so it is applied; an overlap is a judgment
+    # call, so it is only offered (see services/canonical_systems).
+    canonical = assessment["canonical"]
+    applied = canonical["id"] if canonical and canonical["basis"] == "exact" else None
     system = await systems_svc.create_system(
         uid, project_id=project_id, name=name,
         description=description or None, color=color or None,
+        canonical_id=applied,
     )
     if system is None:
         raise ValueError(f"cannot create system in project {project_id} (no write access)")
-    return system.to_dict()
+    out = system.to_dict()
+    if applied:
+        out["canonical_note"] = (
+            f"Mapped to the global area '{canonical['name']}' — the same "
+            "spelling-insensitive name. Your System keeps the name you gave it."
+        )
+    elif canonical:
+        out["canonical_suggestion"] = {
+            **canonical,
+            "message": (
+                f"The global catalog has '{canonical['name']}', which may be "
+                f"this same area. If it is, map_system_to_canonical("
+                f"{system.id}, {canonical['id']}) so records and rules about "
+                "this area line up across projects. If this area is specific "
+                "to this project, ignore it — unmapped is a valid state."
+            ),
+        }
+    return out
 
 
 async def list_systems(project_id: int, include_archived: bool = False) -> dict:
@@ -322,6 +355,64 @@ async def delete_system(system_id: int) -> dict:
     return {"message": f"System {system_id} deleted."}
 
 
+async def list_canonical_systems() -> dict:
+    """The GLOBAL vocabulary of area names, shared by every project.
+
+    These are the standard names to prefer when creating a System, so the same
+    word means the same thing in every project on the instance — and, from
+    milestone 307, the ids a cross-project record can point at. A project's own
+    System keeps whatever name the project calls the area; mapping it here is
+    an association, never a rename.
+
+    Reach for it before create_system when the area is an ordinary one (CI,
+    auth, storage, the API, the UI), and pass the matching `canonical_id`.
+    """
+    entries = await canonical_systems_svc.list_canonical_systems()
+    return {"canonical_systems": [e.to_dict() for e in entries]}
+
+
+async def propose_canonical_mappings(project_id: int) -> dict:
+    """Suggest a global area for each of this project's UNMAPPED Systems.
+
+    Returns PROPOSALS ONLY — nothing is written. Confirm the ones that are
+    right with map_system_to_canonical(system_id, canonical_id); ignore the
+    rest. Each carries a `basis`:
+
+    - `exact`   — the names reduce to the same match key ("CI and Release" vs
+      "CI & Release"). Safe to confirm without much thought.
+    - `overlap` — they share a meaningful word ("CI & runners" vs "CI &
+      Release"). A judgment call: confirm only if they really are the same
+      area, since a wrong mapping surfaces cross-project records in the wrong
+      place.
+
+    A System with no proposal is not a problem — unmapped is a valid resting
+    state, and a genuinely project-specific area should stay that way.
+    """
+    uid = current_user_id()
+    return {"proposals": await canonical_systems_svc.propose_mappings(uid, project_id)}
+
+
+async def map_system_to_canonical(system_id: int, canonical_id: int = 0) -> dict:
+    """Map one of a project's Systems onto a global area (or clear it).
+
+    Sets `canonical_id` and NOTHING else — the System's name, charter and every
+    record tagged to it are untouched. Pass canonical_id=0 to unmap.
+
+    Args:
+        canonical_id: id from list_canonical_systems; 0 clears the mapping.
+    """
+    uid = current_user_id()
+    system = await canonical_systems_svc.set_system_canonical(
+        uid, system_id, canonical_id or None,
+    )
+    if system is None:
+        raise ValueError(
+            f"system {system_id} not found, no write access, "
+            f"or canonical_id {canonical_id} is not a live catalog entry"
+        )
+    return system.to_dict()
+
+
 def register(mcp) -> None:
     for fn in (
         create_system,
@@ -330,5 +421,8 @@ def register(mcp) -> None:
         update_system,
         list_system_records,
         delete_system,
+        list_canonical_systems,
+        propose_canonical_mappings,
+        map_system_to_canonical,
     ):
         mcp.tool(name=fn.__name__)(fn)

src/scribe/models/__init__.py

@@ -25,7 +25,7 @@ from scribe.models.user import User  # noqa: E402, F401
 from scribe.models.app_log import AppLog  # noqa: E402, F401
 from scribe.models.password_reset import PasswordResetToken  # noqa: E402, F401
 from scribe.models.invitation import InvitationToken  # noqa: E402, F401
-from scribe.models.embedding import NoteEmbedding  # noqa: E402, F401
+from scribe.models.embedding import NoteEmbedding, RuleEmbedding  # noqa: E402, F401
 from scribe.models.retrieval_log import RetrievalLog  # noqa: E402, F401
 from scribe.models.note_usage import NoteUsageEvent  # noqa: E402, F401
 from scribe.models.project import Project  # noqa: E402, F401
@@ -39,8 +39,11 @@ from scribe.models.share import NoteShare, ProjectShare  # noqa: E402, F401
 from scribe.models.notification import Notification  # noqa: E402, F401
 from scribe.models.api_key import ApiKey  # noqa: E402, F401
 from scribe.models.user_profile import UserProfile  # noqa: E402, F401
+# Imported before rulebook: rule_systems foreign-keys canonical_systems.
+from scribe.models.canonical_system import CanonicalSystem  # noqa: E402, F401
 from scribe.models.rulebook import (  # noqa: E402, F401
-    Rulebook, RulebookTopic, Rule, project_rulebook_subscriptions,
+    Rulebook, RulebookTopic, Rule, RuleRelation, project_rulebook_subscriptions,
+    rule_systems,
 )
 from scribe.models.repo_binding import RepoBinding  # noqa: E402, F401
 from scribe.models.forge_connection import ForgeConnection  # noqa: E402, F401

src/scribe/models/canonical_system.py

@@ -0,0 +1,58 @@
+from sqlalchemy import Index, Integer, Text, text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from scribe.models import Base
+from scribe.models.base import SoftDeleteMixin, TimestampMixin, iso
+
+
+class CanonicalSystem(Base, TimestampMixin, SoftDeleteMixin):
+    """A GLOBAL area name — the shared vocabulary every project's Systems
+    can point at (milestone 307, decision note 3026).
+
+    A `System` is per-project and NOT NULL on project_id, so nothing outside a
+    project can reference one: a rule that applies across projects has no way
+    to say "this is about CI" without chaining itself to one project's row.
+    This table is that join key. It carries no `user_id` on purpose — a shared
+    project must INHERIT the vocabulary rather than re-earn it, so the catalog
+    is global and the same word means the same thing in every install.
+
+    It is a convergence aid, never a gate: `systems.canonical_id` is nullable,
+    an unmapped System stays fully usable, and `record_systems` never sees this
+    table at all — the local name is a legitimate local label and is never
+    rewritten to match.
+
+    `slug` is the match key, not a display value. It folds the spelling
+    differences that produced four names for one area on the author's own
+    instance ("CI & Release" / "CI and Release" / "CI & release"): an exact slug
+    hit maps automatically, and anything short of that becomes a proposal for a
+    human to confirm. See services/canonical_systems.canonical_slug.
+    """
+
+    __tablename__ = "canonical_systems"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(Text, nullable=False)
+    # Normalized match key — unique among LIVE rows, so a soft-deleted entry
+    # doesn't block recreating the same area (the partial-unique convention
+    # rules/topics already use).
+    slug: Mapped[str] = mapped_column(Text, nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    order_index: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
+
+    __table_args__ = (
+        Index(
+            "uq_canonical_systems_slug", "slug",
+            unique=True, postgresql_where=text("deleted_at IS NULL"),
+        ),
+    )
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "slug": self.slug,
+            "description": self.description,
+            "order_index": self.order_index,
+            "created_at": iso(self.created_at),
+            "updated_at": iso(self.updated_at),
+        }

src/scribe/models/embedding.py

@@ -1,7 +1,7 @@
 from datetime import datetime, timezone
 
 from pgvector.sqlalchemy import Vector
-from sqlalchemy import DateTime, ForeignKey, Integer, Text
+from sqlalchemy import BigInteger, DateTime, ForeignKey, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column
 
 from scribe.models import Base
@@ -45,3 +45,49 @@ class NoteEmbedding(Base):
         DateTime(timezone=True),
         default=lambda: datetime.now(timezone.utc),
     )
+
+
+class RuleEmbedding(Base):
+    """One embedding vector per CHUNK of a rule (milestone 307, note 3026).
+
+    A SIBLING of NoteEmbedding rather than a generalisation of it, decided
+    deliberately:
+
+    - The embedding ROW could have been made polymorphic. The SEARCH could not.
+      `semantic_search_notes` is a long function of Note-specific scoping —
+      the visibility clause, the supersession penalty, note_type/task_kind and
+      system filters — and a rule shares none of it. Rules scope by rulebook
+      ownership and project applicability instead.
+    - Generalising the row while still needing two searches is the worst of
+      both: a polymorphic key with referential integrity to neither table, on
+      the path every session start runs, to share four columns.
+    - What is genuinely common is BEHAVIOUR, not storage — get_embedding,
+      chunk_document, embedding_text and CHUNKER_VERSION are already free
+      functions and are reused as-is. Sharing those is the DRY win; sharing
+      the table would have been the DRY costume.
+
+    No `user_id`: NoteEmbedding carries one and its own search deliberately
+    ignores it (scoping on the note instead, or shared records become
+    unreachable). Rather than repeat a column that exists to be ignored, a
+    rule's reach is resolved by joining the rule.
+    """
+
+    __tablename__ = "rule_embeddings"
+
+    rule_id: Mapped[int] = mapped_column(
+        BigInteger,
+        ForeignKey("rules.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    chunk_index: Mapped[int] = mapped_column(Integer, primary_key=True)
+    embedding: Mapped[list] = mapped_column(Vector(EMBEDDING_DIM), nullable=False)
+    # Exactly what this vector encodes — inspectable when a ranking surprises.
+    # For a rule this is the trigger-first document, NOT the rule's `why`:
+    # `why` is dated incident narrative and would drag every rule toward one
+    # centroid (measured in note 2485).
+    chunk_text: Mapped[str] = mapped_column(Text, nullable=False)
+    chunker_version: Mapped[int] = mapped_column(Integer, nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+    )

src/scribe/models/rulebook.py

@@ -1,10 +1,13 @@
 from datetime import datetime, timezone
 
-from sqlalchemy import BigInteger, Boolean, Column, DateTime, ForeignKey, Index, Integer, Table, Text, text
+from sqlalchemy import (
+    BigInteger, Boolean, Column, DateTime, ForeignKey, Index, Integer, Table,
+    Text, UniqueConstraint, text,
+)
 from sqlalchemy.orm import Mapped, mapped_column
 
 from scribe.models import Base
-from scribe.models.base import SoftDeleteMixin, TimestampMixin, iso
+from scribe.models.base import CreatedAtMixin, SoftDeleteMixin, TimestampMixin, iso
 
 
 class Rulebook(Base, TimestampMixin, SoftDeleteMixin):
@@ -90,8 +93,26 @@ class Rule(Base, TimestampMixin, SoftDeleteMixin):
     )
     title: Mapped[str] = mapped_column(Text)
     statement: Mapped[str] = mapped_column(Text)
+    # WHEN this rule applies — the trigger, not the instruction. Required of
+    # new rules at the service layer and nullable here, because rules written
+    # before migration 0088 have none and a migration cannot invent one.
+    # It carries three jobs at once (note 3026): it is the tier test made
+    # concrete, the readable form of the canon tag, and the half of the
+    # document that makes a rule findable by meaning.
+    when_to_apply: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # always_on = preloaded into every session, as every rule is today.
+    # conditional = reachable, and surfaced when its trigger fires. The
+    # default preserves existing behaviour exactly: nothing stops binding
+    # because of an upgrade. CHECK ck_rules_tier (migration 0088, rule 36).
+    tier: Mapped[str] = mapped_column(Text, default="always_on", server_default="always_on")
     why: Mapped[str | None] = mapped_column(Text, nullable=True)
     how_to_apply: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # The record that caused this rule — the edge notes and tasks already
+    # have. Rule 46's `why` names note 2813 in prose; this is that link as a
+    # field, so it survives a rewording of the paragraph.
+    arose_from_id: Mapped[int | None] = mapped_column(
+        BigInteger, ForeignKey("notes.id", ondelete="SET NULL"), nullable=True
+    )
     order_index: Mapped[int] = mapped_column(Integer, default=0)
 
     def to_dict(self) -> dict:
@@ -101,14 +122,78 @@ class Rule(Base, TimestampMixin, SoftDeleteMixin):
             "project_id": self.project_id,
             "title": self.title,
             "statement": self.statement,
+            "when_to_apply": self.when_to_apply or "",
+            "tier": self.tier,
             "why": self.why or "",
             "how_to_apply": self.how_to_apply or "",
+            "arose_from_id": self.arose_from_id,
             "order_index": self.order_index,
             "created_at": iso(self.created_at),
             "updated_at": iso(self.updated_at),
         }
 
 
+# Which global AREA a rule is about (milestone 307). Points at the canonical
+# catalog, NEVER at a project's `systems` row: a rule that spans projects
+# cannot be chained to one project's vocabulary. This is the edge three
+# projects were drawing by hand, as rule text copied into a System's charter.
+rule_systems = Table(
+    "rule_systems",
+    Base.metadata,
+    Column("rule_id", BigInteger, ForeignKey("rules.id", ondelete="CASCADE"), primary_key=True),
+    Column("canonical_id", Integer, ForeignKey("canonical_systems.id", ondelete="CASCADE"), primary_key=True),
+    Column("created_at", DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)),
+)
+
+
+class RuleRelation(Base, CreatedAtMixin):
+    """A typed edge between two rules. Each kind exists because its ABSENCE
+    forced a workaround somewhere in the operator's rulebook (note 3026).
+
+    - ``co_surfaces`` — these fail together, so they must arrive together.
+      Without it, the only way to guarantee that was to merge them into one
+      row, which is what happened to rule 46: split into 144, folded back the
+      same day because "either rule could surface without the other."
+      Symmetric in meaning; stored once and read both ways.
+    - ``overrides`` — this rule supersedes that one for its scope. Only
+      *suppression* existed, so an override had to be written as a parallel
+      rule that then drifts from its parent.
+    - ``elaborates`` — this rule adds local specifics to that one; surfacing
+      the parent brings the addendum with it.
+
+    ``note`` records WHY the edge was drawn, for the same reason a rule
+    carries `why`: a later reader deciding whether it still holds needs the
+    reasoning, not just the fact.
+    """
+
+    __tablename__ = "rule_relations"
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    from_rule_id: Mapped[int] = mapped_column(
+        BigInteger, ForeignKey("rules.id", ondelete="CASCADE"), index=True
+    )
+    to_rule_id: Mapped[int] = mapped_column(
+        BigInteger, ForeignKey("rules.id", ondelete="CASCADE"), index=True
+    )
+    # CHECK ck_rule_relations_kind (migration 0088, rule 36).
+    kind: Mapped[str] = mapped_column(Text)
+    note: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    __table_args__ = (
+        UniqueConstraint("from_rule_id", "to_rule_id", "kind", name="uq_rule_relations_edge"),
+    )
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "from_rule_id": self.from_rule_id,
+            "to_rule_id": self.to_rule_id,
+            "kind": self.kind,
+            "note": self.note or "",
+            "created_at": iso(self.created_at),
+        }
+
+
 # Pure many-to-many — no model class, just the join table.
 project_rulebook_subscriptions = Table(
     "project_rulebook_subscriptions",

src/scribe/models/system.py

@@ -24,6 +24,15 @@ class System(Base, TimestampMixin, SoftDeleteMixin):
         Integer, ForeignKey("projects.id", ondelete="CASCADE")
     )
     name: Mapped[str] = mapped_column(Text, default="", server_default="")
+    # The GLOBAL area this local System is an instance of (milestone 307).
+    # Nullable and SET NULL on purpose: the catalog is a convergence aid, not a
+    # gate — an unmapped System is fully usable, and retiring a canonical entry
+    # must never take a project's System with it. The local `name` is NEVER
+    # rewritten to match the canonical one; this column is the join key, and
+    # the name stays whatever the project calls the area.
+    canonical_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("canonical_systems.id", ondelete="SET NULL"), nullable=True
+    )
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
     color: Mapped[str | None] = mapped_column(Text, nullable=True)
     # active | archived — systems accumulate; archive rather than delete.
@@ -40,6 +49,7 @@ class System(Base, TimestampMixin, SoftDeleteMixin):
             "user_id": self.user_id,
             "project_id": self.project_id,
             "name": self.name,
+            "canonical_id": self.canonical_id,
             "description": self.description,
             "color": self.color,
             "status": self.status,

src/scribe/routes/canonical_systems.py

@@ -0,0 +1,93 @@
+"""Canonical-system routes — the GLOBAL area vocabulary, and the mapping of a
+project's Systems onto it (milestone 307, decision note 3026).
+
+Two shapes live here because they are two halves of one idea:
+
+- `/api/canonical-systems` — the catalog itself. Readable by any signed-in
+  user (it is shared vocabulary, not user data); writable only by an admin,
+  since a global list anyone can extend stops being a shared list.
+- the mapping endpoints — authorised by the PROJECT, because mapping writes a
+  project's own System row. The service enforces both; these are thin wrappers.
+"""
+import logging
+
+from quart import Blueprint, jsonify, request
+
+from scribe.auth import admin_required, get_current_user_id, login_required
+from scribe.routes.utils import not_found
+from scribe.services import canonical_systems as canonical_svc
+from scribe.services.projects import get_project_for_user
+
+logger = logging.getLogger(__name__)
+
+canonical_systems_bp = Blueprint("canonical_systems", __name__, url_prefix="/api")
+
+
+@canonical_systems_bp.route("/canonical-systems", methods=["GET"])
+@login_required
+async def list_canonical_systems_route():
+    entries = await canonical_svc.list_canonical_systems()
+    return jsonify({"canonical_systems": [e.to_dict() for e in entries]})
+
+
+@canonical_systems_bp.route("/canonical-systems", methods=["POST"])
+@admin_required
+async def create_canonical_system_route():
+    uid = get_current_user_id()
+    data = await request.get_json() or {}
+    if not (data.get("name") or "").strip():
+        return jsonify({"error": "name is required"}), 400
+    entry = await canonical_svc.create_canonical_system(
+        uid, data["name"], description=data.get("description"),
+    )
+    if entry is None:
+        return jsonify({"error": "Permission denied"}), 403
+    # The slug duplicate gate answers with the entry that already covers the
+    # area rather than minting a second spelling of it — 409, not a silent
+    # second row (the whole point of the table).
+    if isinstance(entry, dict):
+        return jsonify(entry), 409
+    return jsonify(entry.to_dict()), 201
+
+
+@canonical_systems_bp.route("/canonical-systems/<int:canonical_id>", methods=["PATCH"])
+@admin_required
+async def update_canonical_system_route(canonical_id: int):
+    uid = get_current_user_id()
+    data = await request.get_json() or {}
+    fields = {k: v for k, v in data.items() if k in ("name", "description", "order_index")}
+    entry = await canonical_svc.update_canonical_system(uid, canonical_id, **fields)
+    if entry is None:
+        return not_found("Canonical system")
+    return jsonify(entry.to_dict())
+
+
+@canonical_systems_bp.route(
+    "/projects/<int:project_id>/canonical-proposals", methods=["GET"]
+)
+@login_required
+async def propose_canonical_mappings_route(project_id: int):
+    """Proposals only — this endpoint writes nothing. The PUT below applies one."""
+    uid = get_current_user_id()
+    if await get_project_for_user(uid, project_id) is None:
+        return not_found("Project")
+    return jsonify({"proposals": await canonical_svc.propose_mappings(uid, project_id)})
+
+
+@canonical_systems_bp.route("/systems/<int:system_id>/canonical", methods=["PUT"])
+@login_required
+async def map_system_to_canonical_route(system_id: int):
+    """Map or unmap one System. Body: {"canonical_id": <id>|null}.
+
+    Sets that column and nothing else — no rename, no change to which records
+    are tagged to the System.
+    """
+    uid = get_current_user_id()
+    data = await request.get_json() or {}
+    canonical_id = data.get("canonical_id")
+    if canonical_id is not None and not isinstance(canonical_id, int):
+        return jsonify({"error": "canonical_id must be an integer or null"}), 400
+    system = await canonical_svc.set_system_canonical(uid, system_id, canonical_id)
+    if system is None:
+        return not_found("System or canonical system")
+    return jsonify(system.to_dict())

src/scribe/routes/plugin.py

@@ -129,6 +129,11 @@ async def write_path_prior_art():
                              surfaced. A separate channel on purpose: a reuse
                              hint shown early must not suppress the record-sync
                              nudge when the recorded file is edited later.
+        exclude_rule_ids (opt) — comma-separated RULE ids already surfaced
+                             this session. Its own channel like the three
+                             above, and for the same reason: a rule named
+                             twenty turns ago should not be re-offered on
+                             every subsequent write.
         exclude_derive (opt) — comma-separated derive keys (a derive group id
                              or `canon:<snippet_id>`) already named this
                              session by the ledger arm (#2900); its own
@@ -151,6 +156,7 @@ async def write_path_prior_art():
     exclude_derive = [
         p.strip() for p in (request.args.get("exclude_derive") or "").split(",") if p.strip()
     ]
+    exclude_rule_ids = _int_list(request.args.get("exclude_rule_ids"))
     shapes = _parse_shapes(request.args.get("shapes") or "")
     api_key = getattr(g, "api_key", None)
     may_stamp = api_key is None or getattr(api_key, "scope", "") == "write"
@@ -161,6 +167,7 @@ async def write_path_prior_art():
         stamp_shapes=shapes if may_stamp else None,
         repo_key=repo_bindings_svc.normalize_repo_key(repo) if repo else "",
         exclude_derive=exclude_derive,
+        exclude_rule_ids=exclude_rule_ids,
     )
     return jsonify(result)
 

src/scribe/routes/rulebooks.py

@@ -162,33 +162,73 @@ async def create_rule(topic_id: int):
             why=data.get("why", ""),
             how_to_apply=data.get("how_to_apply", ""),
             order_index=data.get("order_index", 0),
+            when_to_apply=data.get("when_to_apply", ""),
+            tier=data.get("tier", "always_on"),
+            arose_from_id=data.get("arose_from_id", 0) or 0,
         )
     except ValueError as exc:
         return jsonify({"error": str(exc)}), 404
-    return jsonify(rule.to_dict()), 201
+    return jsonify(await rulebooks_svc.rule_detail(
+        get_current_user_id(), rule, data.get("system_ids"),
+    )), 201
 
 
 @rulebooks_bp.get("/rules/<int:rule_id>")
 @login_required
 async def get_rule(rule_id: int):
-    rule = await rulebooks_svc.get_rule(rule_id, get_current_user_id())
+    uid = get_current_user_id()
+    rule = await rulebooks_svc.get_rule(rule_id, uid)
     if rule is None:
         return jsonify({"error": "rule not found"}), 404
-    return jsonify(rule.to_dict())
+    return jsonify(await rulebooks_svc.rule_detail(uid, rule))
 
 
 @rulebooks_bp.patch("/rules/<int:rule_id>")
 @login_required
 async def update_rule(rule_id: int):
     data = await request.get_json() or {}
+    uid = get_current_user_id()
     fields = {
         k: v for k, v in data.items()
-        if k in ("title", "statement", "why", "how_to_apply", "order_index")
+        if k in ("title", "statement", "why", "how_to_apply", "order_index",
+                 "when_to_apply", "tier", "arose_from_id")
     }
-    rule = await rulebooks_svc.update_rule(rule_id, get_current_user_id(), **fields)
+    rule = await rulebooks_svc.update_rule(rule_id, uid, **fields)
     if rule is None:
         return jsonify({"error": "rule not found"}), 404
-    return jsonify(rule.to_dict())
+    return jsonify(await rulebooks_svc.rule_detail(uid, rule, data.get("system_ids")))
+
+
+@rulebooks_bp.post("/rules/<int:rule_id>/relations")
+@login_required
+async def relate_rules(rule_id: int):
+    """Draw a typed edge FROM this rule to another.
+
+    Body: {"to_rule_id": N, "kind": "co_surfaces"|"overrides"|"elaborates",
+    "note": "..."}. Idempotent — re-drawing an edge returns the existing one.
+    """
+    data = await request.get_json() or {}
+    to_rule_id = data.get("to_rule_id")
+    if not isinstance(to_rule_id, int):
+        return jsonify({"error": "to_rule_id is required"}), 400
+    try:
+        relation = await rulebooks_svc.add_rule_relation(
+            get_current_user_id(), rule_id, to_rule_id,
+            data.get("kind", ""), data.get("note", ""),
+        )
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+    if relation is None:
+        return jsonify({"error": "rule not found"}), 404
+    return jsonify(relation.to_dict()), 201
+
+
+@rulebooks_bp.delete("/rule-relations/<int:relation_id>")
+@login_required
+async def unrelate_rules(relation_id: int):
+    if not await rulebooks_svc.remove_rule_relation(get_current_user_id(), relation_id):
+        return jsonify({"error": "relation not found"}), 404
+    return "", 204
 
 
 @rulebooks_bp.delete("/rules/<int:rule_id>")
@@ -332,7 +372,12 @@ async def create_project_rule(project_id: int):
             why=data.get("why", ""),
             how_to_apply=data.get("how_to_apply", ""),
             order_index=data.get("order_index", 0),
+            when_to_apply=data.get("when_to_apply", ""),
+            tier=data.get("tier", "always_on"),
+            arose_from_id=data.get("arose_from_id", 0) or 0,
         )
     except ValueError as exc:
         return jsonify({"error": str(exc)}), 404
-    return jsonify(rule.to_dict()), 201
+    return jsonify(await rulebooks_svc.rule_detail(
+        get_current_user_id(), rule, data.get("system_ids"),
+    )), 201

src/scribe/routes/systems.py

@@ -62,14 +62,38 @@ async def create_system_route(project_id: int):
     data = await request.get_json() or {}
     if not (data.get("name") or "").strip():
         return jsonify({"error": "name is required"}), 400
+    # The same gate the MCP door enforces. It lived only in the tool layer
+    # until now, which is exactly how the web UI shipped without gates the
+    # agent surface had (#2482) — one service call, one answer (rule 33).
+    assessment = await systems_svc.assess_system_name(uid, project_id, data["name"])
+    duplicate = assessment["duplicate"]
+    if duplicate and not data.get("force"):
+        return jsonify({
+            "duplicate": True,
+            "existing_id": duplicate["id"],
+            "error": (
+                f"“{duplicate['name']}” already covers this area in this "
+                "project. Tag records to it, or rename it if its charter has "
+                "moved on — a second System with the same name splits the "
+                "area's records across two piles."
+            ),
+        }), 409
+    canonical = assessment["canonical"]
+    # Exact is mechanical and applied; overlap is a judgment call and is only
+    # offered back for the form to present.
+    applied = canonical["id"] if canonical and canonical["basis"] == "exact" else None
     system = await systems_svc.create_system(
         uid, project_id=project_id, name=data["name"],
         description=data.get("description"), color=data.get("color"),
         order_index=data.get("order_index", 0),
+        canonical_id=data.get("canonical_id") or applied,
     )
     if system is None:
         return jsonify({"error": "Permission denied"}), 403
-    return jsonify(system.to_dict()), 201
+    out = system.to_dict()
+    if canonical and canonical["basis"] == "overlap" and not system.canonical_id:
+        out["canonical_suggestion"] = canonical
+    return jsonify(out), 201
 
 
 @systems_bp.route("/<int:project_id>/systems/<int:system_id>", methods=["GET"])

src/scribe/services/backup.py

@@ -11,6 +11,8 @@ 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.canonical_system import CanonicalSystem
+from scribe.models.rulebook import RuleRelation, rule_systems as rule_systems_t
 from scribe.models.code_shape import CodeShape, CodeShapeEvent, CodeShapeUse
 from scribe.models.project import Project
 from scribe.models.repo_binding import RepoBinding
@@ -69,11 +71,18 @@ _BACKED_UP = [
     "note_usage_events", "repo_bindings", "note_supersessions",
     # v7 (2026-08): the shape ledger (#2787); v8: its history (#2793).
     "code_shapes", "code_shape_events", "code_shape_uses",
+    # v9 (2026-08): the global area catalog (milestone 307). Global, not
+    # user-scoped, so it rides in EVERY export — including a single-user
+    # one, whose Systems would otherwise restore unmapped.
+    "canonical_systems",
+    # v10 (2026-08): a rule's area tag and its typed edges (milestone 307).
+    "rule_systems", "rule_relations",
 ]
 
 # Tables intentionally NOT in the backup, surfaced in the payload so the gap is
 # explicit rather than silent. ACL (groups/shares) is a coherent follow-up;
-# note_embeddings are derived (regenerated from note bodies); api_keys are
+# note_embeddings and rule_embeddings are derived (regenerated at startup
+# from the records themselves, which is also how a chunker bump is handled); api_keys are
 # sensitive credentials; retrieval_logs is observational telemetry that nothing
 # reads for correctness and that grows per query; the rest are
 # transient/operational.
@@ -83,7 +92,7 @@ _BACKED_UP = [
 # like coverage while naming nothing the schema could confirm.
 _NOT_INCLUDED = [
     "groups", "group_memberships", "project_shares", "note_shares",
-    "api_keys", "note_embeddings", "app_logs", "notifications",
+    "api_keys", "note_embeddings", "rule_embeddings", "app_logs", "notifications",
     "invitation_tokens", "password_reset_tokens", "user_profiles",
     "retrieval_logs",
     # Sensitive credentials, same reasoning as api_keys: a backup that carries
@@ -127,12 +136,29 @@ def _rulebook_exclusion_rows(rows) -> list[dict]:
 # same reason: CI has no database, so a serialiser that is a plain function is
 # one that can actually be tested.
 
-def _system_rows(rows) -> list[dict]:
+def _canonical_system_rows(rows) -> list[dict]:
+    """The global area catalog. Carried WITHOUT ids: a restore matches on slug,
+    so a target install that already seeded the standard vocabulary reuses its
+    own rows and only gains the entries an admin added here."""
+    return [
+        {
+            "name": r.name, "slug": r.slug, "description": r.description,
+            "order_index": r.order_index,
+        }
+        for r in rows
+    ]
+
+
+def _system_rows(rows, canonical_slugs: dict[int, str]) -> list[dict]:
+    """A project's Systems. The canonical mapping travels as a SLUG, not an id
+    — the catalog is global and its ids are per-install, so an id would restore
+    pointing at whatever area happened to land on that number."""
     return [
         {
             "id": r.id, "user_id": r.user_id, "project_id": r.project_id,
             "name": r.name, "description": r.description, "color": r.color,
             "status": r.status, "order_index": r.order_index,
+            "canonical_slug": canonical_slugs.get(r.canonical_id or 0),
         }
         for r in rows
     ]
@@ -332,12 +358,34 @@ def _topic_rows(rows) -> list[dict]:
     ]
 
 
+def _rule_system_rows(rows) -> list[dict]:
+    """A rule's area tags, carried by canonical SLUG for the same reason the
+    Systems are: the catalog is global and its ids are per-install."""
+    return [{"rule_id": rule_id, "canonical_slug": slug} for rule_id, slug in rows]
+
+
+def _rule_relation_rows(rows) -> list[dict]:
+    """The typed edges between rules. Carried because they are a JUDGEMENT —
+    someone decided these two fail together, or that one supersedes the other,
+    and nothing in either rule's text records the decision. Lose them and a
+    split rule silently starts arriving half at a time again."""
+    return [
+        {
+            "from_rule_id": r.from_rule_id, "to_rule_id": r.to_rule_id,
+            "kind": r.kind, "note": r.note,
+        }
+        for r in rows
+    ]
+
+
 def _rule_rows(rows) -> list[dict]:
     return [
         {
             "id": r.id, "topic_id": r.topic_id, "project_id": r.project_id,
             "title": r.title, "statement": r.statement, "why": r.why,
             "how_to_apply": r.how_to_apply, "order_index": r.order_index,
+            "when_to_apply": r.when_to_apply, "tier": r.tier,
+            "arose_from_id": r.arose_from_id,
             "created_at": r.created_at.isoformat(),
             "updated_at": r.updated_at.isoformat(),
         }
@@ -363,6 +411,15 @@ async def export_full_backup() -> dict:
         )).scalars().all()
         settings = (await session.execute(select(Setting))).scalars().all()
         systems = (await session.execute(select(System))).scalars().all()
+        canonical_systems = (await session.execute(
+            select(CanonicalSystem).where(CanonicalSystem.deleted_at.is_(None))
+            .order_by(CanonicalSystem.order_index)
+        )).scalars().all()
+        rule_system_rows = (await session.execute(
+            select(rule_systems_t.c.rule_id, CanonicalSystem.slug)
+            .join(CanonicalSystem, CanonicalSystem.id == rule_systems_t.c.canonical_id)
+        )).all()
+        rule_relations = (await session.execute(select(RuleRelation))).scalars().all()
         record_systems = (await session.execute(select(RecordSystem))).scalars().all()
         supersessions = (
             await session.execute(select(NoteSupersession))
@@ -424,7 +481,12 @@ async def export_full_backup() -> dict:
         "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),
+        "canonical_systems": _canonical_system_rows(canonical_systems),
+        "rule_systems": _rule_system_rows(rule_system_rows),
+        "rule_relations": _rule_relation_rows(rule_relations),
+        "systems": _system_rows(
+            systems, {c.id: c.slug for c in canonical_systems}
+        ),
         "record_systems": _record_system_rows(record_systems),
         "design_systems": _design_system_rows(design_systems),
         "design_tokens": _design_token_rows(design_tokens),
@@ -467,6 +529,12 @@ async def export_user_backup(user_id: int) -> dict:
         systems = (await session.execute(
             select(System).where(System.user_id == user_id)
         )).scalars().all()
+        # Global: taken whole even in a per-user export, because the Systems
+        # above reference it and a partial catalog restores partial mappings.
+        canonical_systems = (await session.execute(
+            select(CanonicalSystem).where(CanonicalSystem.deleted_at.is_(None))
+            .order_by(CanonicalSystem.order_index)
+        )).scalars().all()
         system_ids = [sy.id for sy in systems]
         note_ids = [n.id for n in notes]
         # Scoped by the user's SYSTEMS, not their notes: a shared note carrying
@@ -533,6 +601,20 @@ async def export_user_backup(user_id: int) -> dict:
         rules = (await session.execute(
             select(Rule).where(or_(*rule_filters))
         )).scalars().all() if rule_filters else []
+        # Scoped to the rules this export already carries: an edge whose far
+        # end is absent would restore pointing at nothing.
+        _rule_ids = [r.id for r in rules]
+        rule_system_rows = (await session.execute(
+            select(rule_systems_t.c.rule_id, CanonicalSystem.slug)
+            .join(CanonicalSystem, CanonicalSystem.id == rule_systems_t.c.canonical_id)
+            .where(rule_systems_t.c.rule_id.in_(_rule_ids))
+        )).all() if _rule_ids else []
+        rule_relations = (await session.execute(
+            select(RuleRelation).where(
+                RuleRelation.from_rule_id.in_(_rule_ids),
+                RuleRelation.to_rule_id.in_(_rule_ids),
+            )
+        )).scalars().all() if _rule_ids else []
         if project_ids:
             subscriptions = (await session.execute(
                 select(project_rulebook_subscriptions).where(
@@ -583,7 +665,12 @@ async def export_user_backup(user_id: int) -> dict:
         "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),
+        "canonical_systems": _canonical_system_rows(canonical_systems),
+        "rule_systems": _rule_system_rows(rule_system_rows),
+        "rule_relations": _rule_relation_rows(rule_relations),
+        "systems": _system_rows(
+            systems, {c.id: c.slug for c in canonical_systems}
+        ),
         "record_systems": _record_system_rows(record_systems),
         "design_systems": _design_system_rows(design_systems),
         "design_tokens": _design_token_rows(design_tokens),
@@ -697,7 +784,8 @@ async def _restore_v2(data: dict) -> dict:
         "systems": 0, "record_systems": 0, "design_systems": 0,
         "design_tokens": 0, "note_usage_events": 0, "repo_bindings": 0,
         "note_supersessions": 0, "code_shapes": 0, "code_shape_events": 0,
-        "code_shape_uses": 0,
+        "code_shape_uses": 0, "canonical_systems": 0,
+        "rule_systems": 0, "rule_relations": 0,
     }
 
     async with async_session() as session:
@@ -914,6 +1002,11 @@ async def _restore_v2(data: dict) -> dict:
                 statement=r_data.get("statement", ""),
                 why=r_data.get("why") or None,
                 how_to_apply=r_data.get("how_to_apply") or None,
+                when_to_apply=r_data.get("when_to_apply") or None,
+                # A file written before migration 0088 has no tier. always_on
+                # is the pre-0088 behaviour, so an old backup restores rules
+                # that bind exactly as they did when it was taken.
+                tier=r_data.get("tier") or "always_on",
                 order_index=r_data.get("order_index", 0),
                 created_at=_dt(r_data.get("created_at")),
                 updated_at=_dt(r_data.get("updated_at")),
@@ -970,8 +1063,58 @@ async def _restore_v2(data: dict) -> dict:
         # --- v5 sections. Every one is data.get()-guarded, so a v2/v3/v4
         # payload restores without them rather than failing on an absent key.
 
-        # 15. Systems
         system_id_map: dict[int, int] = {}
+
+        # 14c. The global area catalog, matched on SLUG. This install already
+        # has the standard vocabulary from its migrations, so the common case
+        # adds nothing and simply learns which local id each slug is; only an
+        # entry an admin added on the source instance is created here. Runs
+        # BEFORE systems, which resolve their mapping through this map.
+        canonical_id_by_slug: dict[str, int] = {}
+        existing_canonical = (await session.execute(
+            select(CanonicalSystem).where(CanonicalSystem.deleted_at.is_(None))
+        )).scalars().all()
+        for entry in existing_canonical:
+            canonical_id_by_slug[entry.slug] = entry.id
+        for cs_data in data.get("canonical_systems", []):
+            slug = cs_data.get("slug") or ""
+            if not slug or slug in canonical_id_by_slug:
+                continue
+            entry = CanonicalSystem(
+                name=cs_data.get("name", ""), slug=slug,
+                description=cs_data.get("description"),
+                order_index=cs_data.get("order_index", 0),
+            )
+            session.add(entry)
+            await session.flush()
+            canonical_id_by_slug[slug] = entry.id
+            stats["canonical_systems"] += 1
+
+        # 14d. A rule's area tags and its typed edges. Runs HERE, not beside the
+        # rules in section 11, because it needs both maps: the rule ids from
+        # there and the canonical slugs from 14c just above.
+        for rs in data.get("rule_systems", []):
+            mapped_rule = rule_id_map.get(rs.get("rule_id", 0))
+            canonical_id = canonical_id_by_slug.get(rs.get("canonical_slug") or "")
+            if mapped_rule is None or canonical_id is None:
+                continue
+            await session.execute(rule_systems_t.insert().values(
+                rule_id=mapped_rule, canonical_id=canonical_id,
+            ))
+            stats["rule_systems"] += 1
+
+        for rr in data.get("rule_relations", []):
+            mapped_from = rule_id_map.get(rr.get("from_rule_id", 0))
+            mapped_to = rule_id_map.get(rr.get("to_rule_id", 0))
+            if mapped_from is None or mapped_to is None or mapped_from == mapped_to:
+                continue
+            session.add(RuleRelation(
+                from_rule_id=mapped_from, to_rule_id=mapped_to,
+                kind=rr.get("kind", "co_surfaces"), note=rr.get("note") or None,
+            ))
+            stats["rule_relations"] += 1
+
+        # 15. Systems
         for sy_data in data.get("systems", []):
             mapped_uid = user_id_map.get(sy_data.get("user_id", 0))
             mapped_pid = project_id_map.get(sy_data.get("project_id", 0))
@@ -984,6 +1127,9 @@ async def _restore_v2(data: dict) -> dict:
                 color=sy_data.get("color"),
                 status=sy_data.get("status", "active"),
                 order_index=sy_data.get("order_index", 0),
+                # An unknown slug restores UNMAPPED rather than failing: the
+                # System and its records are the payload, the mapping is an aid.
+                canonical_id=canonical_id_by_slug.get(sy_data.get("canonical_slug") or ""),
             )
             session.add(system)
             await session.flush()

src/scribe/services/canonical_systems.py

@@ -0,0 +1,290 @@
+"""The global canonical area vocabulary, and the mapping from a project's
+Systems onto it (milestone 307 step 1, decision note 3026).
+
+A `System` is per-project. Nothing outside a project can reference one, so a
+rule that spans projects has no way to say "this is about CI" without chaining
+itself to one project's row. `CanonicalSystem` is that join key, and it is
+GLOBAL — no `user_id`, so a shared project inherits the vocabulary instead of
+re-earning it.
+
+Two rules govern everything here:
+
+- **Associate, never rewrite.** Mapping a System sets `systems.canonical_id`
+  and nothing else. The local name stays whatever the project calls the area,
+  and `record_systems` is never touched — no record's tags move.
+- **Propose, never decide.** An exact slug hit is mechanical and maps on
+  request; anything short of that is a PROPOSAL a human confirms. "CI &
+  Release" vs "CI & runners" is a judgment call, and the cost of guessing it
+  wrong silently is a rule surfacing in the wrong project.
+
+Reads are open to any authenticated caller (the catalog is shared vocabulary,
+not user data). Writes to the catalog itself are admin-only: a global table
+that anyone can extend is how a shared vocabulary stops being shared.
+"""
+import logging
+import re
+from datetime import datetime, timezone
+
+from sqlalchemy import select
+
+from scribe.models import async_session
+from scribe.models.canonical_system import CanonicalSystem
+from scribe.models.system import System
+from scribe.models.user import User
+from scribe.services import access
+
+logger = logging.getLogger(__name__)
+
+# Tokens that carry no meaning for matching — "&" becomes "and" before the
+# split, so it would otherwise dominate the overlap score of every pair.
+_NOISE_TOKENS = frozenset({"and", "the", "a", "of"})
+
+_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+
+
+def canonical_slug(name: str) -> str:
+    """The match key for an area name — NOT a display value.
+
+    Folds exactly the spelling differences that produced three names for one
+    area on the author's instance: `CI & Release`, `CI and Release` and
+    `CI & release` all slug to `ci-and-release`, so they map mechanically.
+    A real difference survives: `CI & runners` slugs to `ci-and-runners` and
+    goes through the proposal path where a human decides.
+    """
+    lowered = name.strip().lower().replace("&", " and ")
+    return "-".join(_NON_ALNUM.sub(" ", lowered).split())
+
+
+def _tokens(slug: str) -> frozenset[str]:
+    return frozenset(slug.split("-")) - _NOISE_TOKENS
+
+
+async def _is_admin(user_id: int) -> bool:
+    async with async_session() as session:
+        role = await session.scalar(select(User.role).where(User.id == user_id))
+    return role == "admin"
+
+
+async def list_canonical_systems() -> list[CanonicalSystem]:
+    """The whole catalog, in display order. Global — no ownership filter."""
+    async with async_session() as session:
+        result = await session.execute(
+            select(CanonicalSystem)
+            .where(CanonicalSystem.deleted_at.is_(None))
+            .order_by(CanonicalSystem.order_index.asc(), CanonicalSystem.name.asc())
+        )
+        return list(result.scalars().all())
+
+
+async def get_canonical_system(canonical_id: int) -> CanonicalSystem | None:
+    async with async_session() as session:
+        entry = await session.get(CanonicalSystem, canonical_id)
+    return entry if entry is not None and entry.deleted_at is None else None
+
+
+async def find_by_name(name: str) -> CanonicalSystem | None:
+    """The exact-slug lookup — the mechanical half of matching."""
+    slug = canonical_slug(name)
+    if not slug:
+        return None
+    async with async_session() as session:
+        return await session.scalar(
+            select(CanonicalSystem).where(
+                CanonicalSystem.slug == slug,
+                CanonicalSystem.deleted_at.is_(None),
+            )
+        )
+
+
+def _overlap(local: frozenset[str], other: frozenset[str]) -> float:
+    return len(local & other) / max(len(local | other), 1)
+
+
+async def best_overlap(name: str, catalog: list | None = None) -> dict | None:
+    """The closest catalog entry that shares a meaningful word, or None.
+
+    The ONE scorer behind both offers: the create-time suggestion and the
+    review surface. Two scorers would eventually disagree about which area a
+    name resembles, and the operator would be asked one question at create
+    time and a different one at review.
+
+    The threshold is any shared meaningful word, deliberately generous: a
+    wrong offer costs one dismissal, a missing one costs a mapping nobody
+    thinks to make again. Nothing here ever applies — `overlap` is always an
+    offer (see propose_mappings).
+    """
+    slug = canonical_slug(name)
+    if not slug:
+        return None
+    local = _tokens(slug)
+    if not local:
+        return None
+    # A caller already holding the catalog passes it: this runs once per
+    # unmapped System in the review sweep, and re-reading the table each time
+    # would make an N+1 out of a report.
+    if catalog is None:
+        catalog = await list_canonical_systems()
+    best, best_score = None, 0.0
+    for entry in catalog:
+        score = _overlap(local, _tokens(entry.slug))
+        if score > best_score:
+            best, best_score = entry, score
+    if best is None or best_score <= 0:
+        return None
+    return {
+        "id": best.id, "name": best.name,
+        "basis": "overlap", "score": round(best_score, 3),
+    }
+
+
+async def create_canonical_system(
+    user_id: int, name: str, description: str | None = None,
+) -> CanonicalSystem | dict | None:
+    """Add an area to the global catalog. Admin only.
+
+    Duplicate-gated on the SLUG, not the raw name, so "CI and Release" cannot
+    be added alongside "CI & Release" — that is the drift this table exists to
+    end. Returns the existing entry's id instead of creating a second one.
+    """
+    if not await _is_admin(user_id):
+        return None
+    slug = canonical_slug(name)
+    if not slug:
+        return None
+    existing = await find_by_name(name)
+    if existing is not None:
+        return {
+            "duplicate": True,
+            "existing_id": existing.id,
+            "message": (
+                f"'{existing.name}' (#{existing.id}) already covers this area — "
+                f"both names reduce to '{slug}'. Map Systems to it, or "
+                "update_canonical_system if the charter needs revising."
+            ),
+        }
+    async with async_session() as session:
+        highest = await session.scalar(
+            select(CanonicalSystem.order_index)
+            .order_by(CanonicalSystem.order_index.desc())
+            .limit(1)
+        )
+        entry = CanonicalSystem(
+            name=" ".join(name.split()),
+            slug=slug,
+            description=description,
+            order_index=(highest or 0) + 1,
+        )
+        session.add(entry)
+        await session.commit()
+        await session.refresh(entry)
+        return entry
+
+
+async def update_canonical_system(
+    user_id: int, canonical_id: int, **fields: object,
+) -> CanonicalSystem | None:
+    """Rename or re-charter a catalog entry. Admin only.
+
+    A rename recomputes the slug — the display name and the match key must not
+    be allowed to disagree, or the exact-match path silently stops finding it.
+    """
+    if not await _is_admin(user_id):
+        return None
+    allowed = {"name", "description", "order_index"}
+    async with async_session() as session:
+        entry = await session.get(CanonicalSystem, canonical_id)
+        if entry is None or entry.deleted_at is not None:
+            return None
+        for key, value in fields.items():
+            if key in allowed and value is not None:
+                setattr(entry, key, value)
+        if "name" in fields and fields["name"]:
+            entry.name = " ".join(str(fields["name"]).split())
+            entry.slug = canonical_slug(entry.name)
+        entry.updated_at = datetime.now(timezone.utc)
+        await session.commit()
+        await session.refresh(entry)
+        return entry
+
+
+async def set_system_canonical(
+    user_id: int, system_id: int, canonical_id: int | None,
+) -> System | None:
+    """Map (or unmap) one project System onto a catalog entry.
+
+    Authorised by the PROJECT, not the catalog: mapping changes the project's
+    row, so project write access is the right gate (rule 78 — never a bare
+    owner filter). Passing None clears the mapping.
+
+    Touches `canonical_id` and nothing else — the System's own name, charter
+    and record associations are left exactly as they are.
+    """
+    if canonical_id is not None and await get_canonical_system(canonical_id) is None:
+        return None
+    async with async_session() as session:
+        system = await session.get(System, system_id)
+        if system is None or system.deleted_at is not None:
+            return None
+        if not await access.can_write_project(user_id, system.project_id):
+            return None
+        system.canonical_id = canonical_id
+        system.updated_at = datetime.now(timezone.utc)
+        await session.commit()
+        await session.refresh(system)
+        return system
+
+
+async def propose_mappings(user_id: int, project_id: int) -> list[dict]:
+    """Suggest a catalog entry for each of a project's UNMAPPED Systems.
+
+    Returns proposals, never applied changes — `set_system_canonical` is the
+    only thing that writes. Each carries a `basis` so the reviewer knows what
+    they are approving:
+
+    - `exact`   — the two names reduce to the same slug. Mechanical.
+    - `overlap` — they share a meaningful word ("CI & runners" / "CI &
+      Release"). A judgment call, and the reason this is a proposal at all.
+
+    A System with no plausible match simply gets no proposal: unmapped is a
+    perfectly good resting state, so silence here is an answer, not a gap.
+    """
+    if not await access.can_read_project(user_id, project_id):
+        return []
+    catalog = await list_canonical_systems()
+    if not catalog:
+        return []
+    async with async_session() as session:
+        result = await session.execute(
+            select(System).where(
+                System.project_id == project_id,
+                System.canonical_id.is_(None),
+                System.deleted_at.is_(None),
+            ).order_by(System.order_index.asc(), System.created_at.asc())
+        )
+        systems = list(result.scalars().all())
+
+    by_slug = {entry.slug: entry for entry in catalog}
+    proposals: list[dict] = []
+    for system in systems:
+        slug = canonical_slug(system.name)
+        if not slug:
+            continue
+        exact = by_slug.get(slug)
+        if exact is not None:
+            match = {"id": exact.id, "name": exact.name, "basis": "exact", "score": 1.0}
+        else:
+            # Same scorer the create-time offer uses, so the two surfaces can
+            # never name different areas for one System.
+            match = await best_overlap(system.name, catalog)
+            if match is None:
+                continue
+        proposals.append({
+            "system_id": system.id,
+            "system_name": system.name,
+            "canonical_id": match["id"],
+            "canonical_name": match["name"],
+            "basis": match["basis"],
+            "score": match["score"],
+        })
+    proposals.sort(key=lambda p: (-p["score"], p["system_name"]))
+    return proposals

src/scribe/services/embeddings.py

@@ -16,13 +16,18 @@ import os
 
 from collections.abc import Sequence
 
+from typing import TYPE_CHECKING
+
 from sqlalchemy import delete, or_, select
 
 from scribe.models import async_session
-from scribe.models.embedding import NoteEmbedding
+from scribe.models.embedding import NoteEmbedding, RuleEmbedding
 from scribe.models.note import Note
 from scribe.services.access import notes_visibility_clause
 
+if TYPE_CHECKING:  # resolves the Rule forward ref without importing at runtime
+    from scribe.models.rulebook import Rule
+
 logger = logging.getLogger(__name__)
 
 # Minimum cosine similarity to include a note in context results.
@@ -612,3 +617,193 @@ async def backfill_note_embeddings() -> None:
         await asyncio.sleep(0.05)  # gentle pacing
 
     logger.info("Embedding backfill complete: %d/%d notes embedded", success, len(notes_to_embed))
+
+
+# ── Rules (milestone 307, note 3026) ────────────────────────────────────
+
+def rule_document(
+    title: str | None, statement: str | None, when_to_apply: str | None,
+) -> tuple[str | None, str | None]:
+    """The (title, body) a rule is EMBEDDED as — trigger first, `why` never.
+
+    Both halves of this are measured, not guessed (note 2485). That pass found
+    the snippet was the only sharp record in the corpus — a 0.153 top-to-second
+    gap against 0.010–0.023 for everything else — and that the cause was its
+    SHAPE: `{name} — {when_to_use}` as the title and `**When to use:** …`
+    repeated in the body, so purpose appears twice in a short document and
+    dominates the vector. This mirrors that exactly.
+
+    And it excludes `why` on the same evidence. `why` is dated incident
+    narrative — rule 46's runs to 4,300 characters of it — and long,
+    multi-topic prose is precisely what made sixteen dev-logs mutually
+    indistinguishable: the average lands on the centroid of "development",
+    which every one of them shares. Adding `why` would not give the vector more
+    to work with; it would give every rule the same thing to work with.
+
+    A rule with no trigger yet degrades to title + statement. It still embeds,
+    just less sharply — which is an argument for backfilling triggers, not an
+    argument for padding the document with whatever text is lying around.
+    """
+    trigger = (when_to_apply or "").strip()
+    name = (title or "").strip()
+    body = (statement or "").strip()
+    if not trigger:
+        return name or None, body or None
+    return (
+        f"{name} — {trigger}" if name else trigger,
+        f"When to apply: {trigger}\n\n{body}" if body else f"When to apply: {trigger}",
+    )
+
+
+async def upsert_rule_embedding(
+    rule_id: int, title: str | None, statement: str | None,
+    when_to_apply: str | None = None,
+) -> None:
+    """Chunk, embed and persist a rule's vectors. Safe to fire-and-forget.
+
+    The note twin's contract, for the same reasons: the document is built HERE
+    so the write path, the backfill and any re-embed share one definition, and
+    replacement is atomic per rule so a concurrent read sees the old chunk set
+    or the new one, never a mixture.
+    """
+    doc_title, doc_body = rule_document(title, statement, when_to_apply)
+    chunks = chunk_document(doc_title, doc_body)
+    try:
+        if not chunks:
+            async with async_session() as session:
+                await session.execute(
+                    delete(RuleEmbedding).where(RuleEmbedding.rule_id == rule_id)
+                )
+                await session.commit()
+            return
+    except Exception:
+        logger.warning("Failed to clear embedding for rule %d", rule_id, exc_info=True)
+        return
+
+    try:
+        vectors = await get_embeddings(chunks)
+    except Exception:
+        logger.debug("Skipping embedding for rule %d — embedder unavailable", rule_id)
+        return
+
+    try:
+        async with async_session() as session:
+            await session.execute(
+                delete(RuleEmbedding).where(RuleEmbedding.rule_id == rule_id)
+            )
+            for index, (chunk, vector) in enumerate(zip(chunks, vectors)):
+                session.add(
+                    RuleEmbedding(
+                        rule_id=rule_id,
+                        chunk_index=index,
+                        embedding=vector,
+                        chunk_text=chunk,
+                        chunker_version=CHUNKER_VERSION,
+                    )
+                )
+            await session.commit()
+    except Exception:
+        logger.warning("Failed to persist embedding for rule %d", rule_id, exc_info=True)
+
+
+async def semantic_search_rules(
+    user_id: int,
+    query: str,
+    limit: int = 5,
+    threshold: float = _SIMILARITY_THRESHOLD,
+    tier: str | None = None,
+) -> list[tuple[float, "Rule"]]:
+    """Return up to *limit* (score, rule) pairs most relevant to *query*.
+
+    Scoped by OWNERSHIP — a rule is the caller's if they own its rulebook or
+    its project. Deliberately not filtered to what currently BINDS a given
+    project: this answers "is there a rule about this", which a person asking
+    wants answered across their whole rulebook. Deciding which rules bind where
+    is the surfacing question, and it has its own machinery
+    (get_applicable_rules) rather than a second, subtly different copy here.
+
+    `tier` narrows to one tier. The write-path hint passes "conditional",
+    because an always-on rule is ALREADY in the session — surfacing it again as
+    a suggestion is pure noise, and noise on a hint that fires on every write
+    is how a hint gets ignored.
+
+    Collapses to best-chunk-per-rule like the note search, so a long rule split
+    across chunks competes once rather than crowding the results with itself.
+
+    Returns an empty list if the embedder is unavailable or on any error.
+    """
+    from scribe.models.project import Project
+    from scribe.models.rulebook import Rule, Rulebook, RulebookTopic
+
+    if not query or not query.strip():
+        return []
+    try:
+        query_vec = await get_embedding(query)
+    except Exception:
+        logger.debug("Rule search skipped — embedder unavailable")
+        return []
+
+    max_distance = min(2.0, max(0.0, 1.0 - threshold))
+    distance = RuleEmbedding.embedding.cosine_distance(query_vec)
+
+    try:
+        async with async_session() as session:
+            rows = (await session.execute(
+                select(Rule, distance.label("distance"))
+                .select_from(RuleEmbedding)
+                .join(Rule, RuleEmbedding.rule_id == Rule.id)
+                .outerjoin(RulebookTopic, Rule.topic_id == RulebookTopic.id)
+                .outerjoin(Rulebook, RulebookTopic.rulebook_id == Rulebook.id)
+                .outerjoin(Project, Rule.project_id == Project.id)
+                .where(
+                    Rule.deleted_at.is_(None),
+                    distance <= max_distance,
+                    # topic_id XOR project_id, so exactly one arm can match.
+                    or_(
+                        Rulebook.owner_user_id == user_id,
+                        Project.user_id == user_id,
+                    ),
+                    *( [Rule.tier == tier] if tier else [] ),
+                )
+                # Overfetch so collapsing chunks to their best row still fills
+                # the page — the same reason the note search overfetches.
+                .order_by(distance)
+                .limit(limit * _CHUNK_OVERFETCH)
+            )).all()
+    except Exception:
+        logger.warning("Rule semantic search failed", exc_info=True)
+        return []
+
+    best: dict[int, tuple[float, object]] = {}
+    for rule, dist in rows:
+        score = 1.0 - float(dist)
+        if rule.id not in best or score > best[rule.id][0]:
+            best[rule.id] = (score, rule)
+    ranked = sorted(best.values(), key=lambda pair: pair[0], reverse=True)
+    return ranked[:limit]
+
+
+async def backfill_rule_embeddings() -> None:
+    """Embed rules that have no current vectors. Runs at startup beside the
+    note backfill; a CHUNKER_VERSION bump re-embeds rather than wiping."""
+    from scribe.models.rulebook import Rule
+
+    try:
+        async with async_session() as session:
+            current = select(RuleEmbedding.rule_id).where(
+                RuleEmbedding.chunker_version == CHUNKER_VERSION
+            )
+            stale = (await session.execute(
+                select(Rule.id, Rule.title, Rule.statement, Rule.when_to_apply)
+                .where(Rule.deleted_at.is_(None), Rule.id.notin_(current))
+            )).all()
+    except Exception:
+        logger.warning("Rule embedding backfill: failed to query rules", exc_info=True)
+        return
+
+    if not stale:
+        logger.info("Rule embedding backfill: all rules current at chunker v%d", CHUNKER_VERSION)
+        return
+    logger.info("Rule embedding backfill: embedding %d rule(s)", len(stale))
+    for rule_id, title, statement, when_to_apply in stale:
+        await upsert_rule_embedding(rule_id, title, statement, when_to_apply)

src/scribe/services/plugin_context.py

@@ -30,7 +30,7 @@ from scribe.services import rulebooks as rulebooks_svc
 from scribe.services import shape_ledger as shape_ledger_svc
 from scribe.services import snippets as snippets_svc
 from scribe.services.access import label_shared_items, owner_names_for
-from scribe.services.embeddings import semantic_search_notes
+from scribe.services.embeddings import semantic_search_notes, semantic_search_rules
 from scribe.services.note_usage import record_surfaced
 from scribe.services.supersession import superseded_ids
 from scribe.services.retrieval_telemetry import record_retrieval
@@ -707,6 +707,7 @@ async def build_write_path_hint(
     stamp_shapes: list[tuple[str, str]] | None = None,
     repo_key: str = "",
     exclude_derive: list[str] | None = None,
+    exclude_rule_ids: list[int] | None = None,
 ) -> dict:
     """Prior-art hint for the plugin's PreToolUse hook on Write/Edit.
 
@@ -766,7 +767,8 @@ async def build_write_path_hint(
     """
     cfg = await get_writepath_config(user_id)
     empty = {"context": "", "note_ids": [], "sync_note_ids": [], "config": cfg,
-             "stamped": [], "divergence": [], "derive": [], "derive_keys": []}
+             "stamped": [], "divergence": [], "derive": [], "derive_keys": [],
+             "rule_ids": []}
     path = (path or "").strip()
     if not cfg["enabled"] or not path:
         return empty
@@ -1036,6 +1038,50 @@ async def build_write_path_hint(
     for arm, ids in by_arm.items():
         record_surfaced(user_id=user_id, note_ids=ids, source=arm)
 
+    # ── Standing rules that may apply here (milestone 307) ──────────────
+    #
+    # A SUGGESTION, not a binding surface, and the distinction is the design
+    # (D7): a rule BINDS by being tagged to an area the project works in,
+    # resolved deterministically at enter_project. This arm reaches for
+    # something weaker and still useful — a conditional rule whose trigger
+    # resembles what is being written, noticed at the moment it is relevant
+    # rather than by being resident in every session.
+    #
+    # CONDITIONAL ONLY. An always-on rule is already in the session; repeating
+    # it here would be noise, and noise on a hint that fires on every write is
+    # how a hint gets ignored.
+    #
+    # Fails open like every other arm: a rule hint must never break a write.
+    rule_ids: list[int] = []
+    try:
+        already = set(exclude_rule_ids or [])
+        hits = await semantic_search_rules(
+            user_id, code or path, limit=2,
+            threshold=cfg["threshold"], tier="conditional",
+        )
+        fresh = [(score, rule) for score, rule in hits if rule.id not in already]
+        for _score, rule in fresh:
+            trigger = (rule.when_to_apply or "").strip()
+            lines.append(
+                f"Standing rule that may apply here — \u201c{rule.title}\u201d"
+                + (f" ({trigger})" if trigger else "")
+                + f". Read it with get_rule({rule.id}) before deciding it "
+                  "does not apply; it is not in this session's loaded set."
+            )
+            rule_ids.append(rule.id)
+        if fresh:
+            # retrieval_logs, NOT note_usage_events: that table's ids are
+            # remapped on a backup restore, so a rule id there would return
+            # attached to whatever note took that number. This one is never
+            # restored, and `source` already separates the surfaces.
+            record_retrieval(
+                user_id=user_id, source="write_path_rule", query=code or path,
+                threshold=cfg["threshold"], limit=2, project_id=project_id,
+                is_task=None, results=fresh,
+            )
+    except Exception:
+        logger.debug("write-path rule arm failed", exc_info=True)
+
     return {
         "context": "\n".join(lines),
         "note_ids": note_ids,
@@ -1045,6 +1091,7 @@ async def build_write_path_hint(
         "divergence": divergence,
         "derive": derive,
         "derive_keys": [d["key"] for d in derive],
+        "rule_ids": rule_ids,
     }
 
 

src/scribe/services/retrieval_telemetry.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from typing import Any
 
 from datetime import datetime, timedelta, timezone
 
@@ -108,11 +109,19 @@ def record_retrieval(
     limit: int | None,
     project_id: int | None,
     is_task: bool | None,
-    results: list[tuple[float, Note]],
+    results: list[tuple[float, Any]],
     duration_ms: float | None = None,
 ) -> None:
     """Fire-and-forget: record one retrieval call.
 
+    `results` needs only `.id` on each record, which is why it is not typed to
+    Note: rules are retrieved too (milestone 307) and land here rather than in
+    note_usage_events. That table's ids are REMAPPED on a backup restore, so a
+    rule id written into it would come back attached to whatever note happened
+    to take that number — silent corruption of the very evidence this exists to
+    provide. retrieval_logs is not restored at all, so it has no such hazard,
+    and `source` already distinguishes the surfaces.
+
     Builds the payload inline (synchronously) then schedules the insert so the
     caller returns immediately. Never raises — telemetry must not affect search.
     """

src/scribe/services/rulebooks.py

@@ -10,9 +10,10 @@ from __future__ import annotations
 import logging
 from typing import Optional
 
-from sqlalchemy import select
+from sqlalchemy import delete as sql_delete, insert, or_, select
 
 from scribe.models import async_session
+from scribe.models.system import System
 from scribe.models.rulebook import Rulebook
 
 logger = logging.getLogger(__name__)
@@ -223,7 +224,7 @@ async def delete_topic(topic_id: int, user_id: int) -> None:
 
 # ── Rule CRUD ──────────────────────────────────────────────────────────
 
-from scribe.models.rulebook import Rule
+from scribe.models.rulebook import Rule, RuleRelation, rule_systems
 
 
 async def _assert_topic_owned(session, topic_id: int, user_id: int) -> None:
@@ -280,9 +281,161 @@ async def _assert_rulebook_rule_owned(session, rule_id: int, user_id: int) -> No
         raise ValueError(f"rule {rule_id} not found or not a rulebook rule")
 
 
+# The vocabularies migration 0088's CHECK constraints enforce. Named here so
+# a caller can be corrected before the database refuses it (rule 36 keeps the
+# two in step; this keeps the error readable).
+TIERS = ("always_on", "conditional")
+RELATION_KINDS = ("co_surfaces", "overrides", "elaborates")
+
+
+def _valid_tier(tier: str) -> str:
+    """An unrecognised tier falls back to always_on — the SAFE direction.
+
+    Getting this wrong the other way would silently stop a rule binding, which
+    is the one failure this whole milestone exists to prevent. A rule that
+    preloads when it did not need to costs context; a rule that quietly stops
+    preloading costs the behaviour it was written for.
+    """
+    return tier if tier in TIERS else "always_on"
+
+
+def rule_brief(rule: Rule, **extra) -> dict:
+    """The shape a rule takes when it is SURFACED rather than opened.
+
+    One builder for every payload that hands rules to an agent, because there
+    were three copies of this dict and they had already diverged — two carried
+    `topic_id`, one didn't, and none carried the timestamps the model has held
+    all along. That omission is why a rule written before the capability it
+    duplicates was indistinguishable, at read time, from one still doing work
+    (the FabledCurator case, note 3026).
+
+    `updated_at` is a DATE, not a stamp: the question it answers is "how old
+    is this?", and a full ISO string across an always-on set is ~2k characters
+    of payload for a precision nobody reads.
+
+    `why` and `how_to_apply` are deliberately NOT here — they are the depth a
+    caller gets from get_rule, and putting them in every listing is the bloat
+    this milestone is about.
+    """
+    out = {
+        "id": rule.id,
+        "title": rule.title,
+        "statement": rule.statement,
+        "topic_id": rule.topic_id,
+        "tier": rule.tier,
+        "updated_at": rule.updated_at.date().isoformat() if rule.updated_at else None,
+    }
+    # Attached only when present (#2483: never a null key that reads as a
+    # capability the record doesn't have).
+    if rule.when_to_apply:
+        out["when_to_apply"] = rule.when_to_apply
+    if rule.arose_from_id:
+        out["arose_from_id"] = rule.arose_from_id
+    out.update({k: v for k, v in extra.items() if v is not None})
+    return out
+
+
+def _refresh_rule_embedding(rule: Rule) -> None:
+    """Re-index a rule after a write. Fire-and-forget, like the note twin.
+
+    Lazy import so this module doesn't pull in the embedder; every exception
+    swallowed because a rule that SAVED must not fail on its index refresh —
+    a stale vector costs a missed search hit, a raised exception costs the
+    write. No running loop (unit tests, scripts) is ordinary, not an error.
+    """
+    try:
+        import asyncio
+
+        from scribe.services.embeddings import upsert_rule_embedding
+
+        asyncio.create_task(
+            upsert_rule_embedding(
+                rule.id, rule.title, rule.statement, rule.when_to_apply,
+            )
+        )
+    except RuntimeError:
+        pass          # no running loop — a sync caller, not a failure
+    except Exception:  # noqa: BLE001 - never let indexing break a write
+        logger.exception("embedding refresh failed for rule %s", rule.id)
+
+
+async def co_surfaced_partners(
+    user_id: int, rule_ids: list[int], exclude_ids: set[int] | None = None,
+) -> list[Rule]:
+    """Rules that must arrive WITH the given ones, because they fail together.
+
+    This is the whole reason `co_surfaces` exists. Rule 144 was split off rule
+    46 and folded back into it the same day, on the correct observation that
+    "either rule could surface without the other and miss exposing a project to
+    what the entire shape is intended to be." Merging was the only fix
+    available; this is the fix that should have been available.
+
+    Two limits, both deliberate:
+
+    - Only rules the caller OWNS. An edge is not a back door into someone
+      else's rulebook.
+    - `exclude_ids` is honoured, and callers pass the project's SUPPRESSIONS.
+      A project that explicitly muted a rule should not have it dragged back in
+      by an edge — the suppression is a decision, and the edge does not
+      outrank it.
+    """
+    if not rule_ids:
+        return []
+    known = set(rule_ids) | (exclude_ids or set())
+    async with async_session() as session:
+        edges = (await session.execute(
+            select(RuleRelation).where(
+                RuleRelation.kind == "co_surfaces",
+                or_(
+                    RuleRelation.from_rule_id.in_(rule_ids),
+                    RuleRelation.to_rule_id.in_(rule_ids),
+                ),
+            )
+        )).scalars().all()
+        partners = {
+            (edge.to_rule_id if edge.from_rule_id in known else edge.from_rule_id)
+            for edge in edges
+        } - known
+        if not partners:
+            return []
+        # Ownership re-checked per partner rather than assumed from the edge.
+        out = []
+        for partner_id in sorted(partners):
+            rule = await _fetch_owned_rule(session, partner_id, user_id)
+            if rule is not None:
+                out.append(rule)
+        return out
+
+
+async def rule_detail(user_id: int, rule: Rule, system_ids: list[int] | None = None) -> dict:
+    """The full record, with its areas and edges attached.
+
+    ONE seam for both doors and every write path, so create, update and get
+    cannot disagree about what a rule looks like coming back — the same
+    reasoning as attach_relations for notes (#2859), and the same reasoning
+    rule_brief exists for one level down.
+
+    `system_ids=None` means "leave the tags alone"; a list (including [])
+    REPLACES them.
+    """
+    if system_ids is not None:
+        await set_rule_systems(rule.id, user_id, system_ids)
+    data = rule.to_dict()
+    systems = (await list_rule_systems([rule.id])).get(rule.id, [])
+    relations = (await list_rule_relations([rule.id])).get(rule.id, [])
+    # Attached only when present (#2483): an empty key reads as a capability
+    # the record has and isn't using, which is a different claim.
+    if systems:
+        data["systems"] = systems
+    if relations:
+        data["relations"] = relations
+    return data
+
+
 async def create_rule(
     topic_id: int, user_id: int, title: str, statement: str,
     why: str = "", how_to_apply: str = "", order_index: int = 0,
+    when_to_apply: str = "", tier: str = "always_on", arose_from_id: int = 0,
 ) -> Rule:
     async with async_session() as session:
         await _assert_topic_owned(session, topic_id, user_id)
@@ -290,19 +443,24 @@ async def create_rule(
             topic_id=topic_id,
             title=title,
             statement=statement,
+            when_to_apply=when_to_apply or None,
+            tier=_valid_tier(tier),
             why=why or None,
             how_to_apply=how_to_apply or None,
+            arose_from_id=arose_from_id or None,
             order_index=order_index,
         )
         session.add(rule)
         await session.commit()
         await session.refresh(rule)
+        _refresh_rule_embedding(rule)
         return rule
 
 
 async def create_project_rule(
     project_id: int, user_id: int, title: str, statement: str,
     why: str = "", how_to_apply: str = "", order_index: int = 0,
+    when_to_apply: str = "", tier: str = "always_on", arose_from_id: int = 0,
 ) -> Rule:
     """Create a rule scoped to a single project (no rulebook ceremony).
 
@@ -316,13 +474,17 @@ async def create_project_rule(
             project_id=project_id,
             title=title,
             statement=statement,
+            when_to_apply=when_to_apply or None,
+            tier=_valid_tier(tier),
             why=why or None,
             how_to_apply=how_to_apply or None,
+            arose_from_id=arose_from_id or None,
             order_index=order_index,
         )
         session.add(rule)
         await session.commit()
         await session.refresh(rule)
+        _refresh_rule_embedding(rule)
         return rule
 
 
@@ -454,6 +616,17 @@ async def list_always_on_rules(
                 Rule.deleted_at.is_(None),
                 RulebookTopic.deleted_at.is_(None),
                 Rulebook.deleted_at.is_(None),
+                # TIER (milestone 307). This is the SESSION-START call, made
+                # before any project is in scope — there is no area vocabulary
+                # to match a conditional rule against yet, so only the
+                # unconditional tier belongs here. A conditional rule reaches a
+                # session through enter_project (by area) or search (by
+                # meaning), not by being resident.
+                #
+                # Behaviour is unchanged until rules are actually re-tiered:
+                # `tier` defaults to always_on, so every existing rule still
+                # arrives exactly as it did.
+                Rule.tier == "always_on",
             )
         )
         if project_id:
@@ -513,15 +686,175 @@ async def update_rule(rule_id: int, user_id: int, **fields) -> Optional[Rule]:
         rule = await _fetch_owned_rule(session, rule_id, user_id)
         if rule is None:
             return None
-        allowed = {"title", "statement", "why", "how_to_apply", "order_index"}
+        allowed = {
+            "title", "statement", "why", "how_to_apply", "order_index",
+            "when_to_apply", "tier", "arose_from_id",
+        }
         for key, value in fields.items():
             if key in allowed and value is not None:
-                setattr(rule, key, value)
+                setattr(rule, key, _valid_tier(value) if key == "tier" else value)
         await session.commit()
         await session.refresh(rule)
+        _refresh_rule_embedding(rule)
         return rule
 
 
+# ── Canon tags + typed edges (milestone 307) ───────────────────────────
+
+async def set_rule_systems(
+    rule_id: int, user_id: int, canonical_ids: list[int],
+) -> list[int] | None:
+    """Replace which global AREAS a rule is about. None if not owned.
+
+    Set-semantics like set_record_systems: the list given IS the state after,
+    so an empty list clears the tags. Points at the canonical catalog, never a
+    project's System — a family rule tagged to one project's row would bind
+    itself to that project's vocabulary.
+    """
+    from scribe.models.canonical_system import CanonicalSystem
+    from scribe.models.rulebook import rule_systems as rule_systems_t
+
+    async with async_session() as session:
+        rule = await _fetch_owned_rule(session, rule_id, user_id)
+        if rule is None:
+            return None
+        wanted = set(canonical_ids or [])
+        if wanted:
+            live = set((await session.execute(
+                select(CanonicalSystem.id).where(
+                    CanonicalSystem.id.in_(wanted),
+                    CanonicalSystem.deleted_at.is_(None),
+                )
+            )).scalars().all())
+            # Silently dropping an unknown id would leave the caller believing
+            # a tag exists; keep only the live ones and report what stuck.
+            wanted &= live
+        await session.execute(
+            sql_delete(rule_systems_t).where(rule_systems_t.c.rule_id == rule_id)
+        )
+        for canonical_id in sorted(wanted):
+            await session.execute(
+                insert(rule_systems_t).values(rule_id=rule_id, canonical_id=canonical_id)
+            )
+        await session.commit()
+        return sorted(wanted)
+
+
+async def list_rule_systems(rule_ids: list[int]) -> dict[int, list[dict]]:
+    """The canon tags for a batch of rules, keyed by rule id.
+
+    Batched on purpose: the surfacing paths ask about a whole payload of rules
+    at once, and one query per rule would turn every session start into an
+    N+1.
+    """
+    from scribe.models.canonical_system import CanonicalSystem
+    from scribe.models.rulebook import rule_systems as rule_systems_t
+
+    if not rule_ids:
+        return {}
+    async with async_session() as session:
+        rows = (await session.execute(
+            select(rule_systems_t.c.rule_id, CanonicalSystem.id, CanonicalSystem.name)
+            .join(CanonicalSystem, CanonicalSystem.id == rule_systems_t.c.canonical_id)
+            .where(
+                rule_systems_t.c.rule_id.in_(rule_ids),
+                CanonicalSystem.deleted_at.is_(None),
+            )
+            .order_by(CanonicalSystem.order_index)
+        )).all()
+    out: dict[int, list[dict]] = {}
+    for rule_id, canonical_id, name in rows:
+        out.setdefault(rule_id, []).append({"id": canonical_id, "name": name})
+    return out
+
+
+async def add_rule_relation(
+    user_id: int, from_rule_id: int, to_rule_id: int, kind: str, note: str = "",
+) -> RuleRelation | None:
+    """Draw a typed edge between two rules. None if either isn't owned.
+
+    Both ends are ownership-checked: an edge is only meaningful if the drawer
+    can see both rules, and a one-sided edge would surface a rule the caller
+    has no business reading.
+
+    Idempotent — re-drawing an existing edge returns it rather than raising, so
+    a true-up pass can be re-run without cleaning up first.
+    """
+    if kind not in RELATION_KINDS:
+        raise ValueError(f"kind must be one of {RELATION_KINDS}, got {kind!r}")
+    if from_rule_id == to_rule_id:
+        raise ValueError("a rule cannot relate to itself")
+    async with async_session() as session:
+        for rid in (from_rule_id, to_rule_id):
+            if await _fetch_owned_rule(session, rid, user_id) is None:
+                return None
+        existing = await session.scalar(
+            select(RuleRelation).where(
+                RuleRelation.from_rule_id == from_rule_id,
+                RuleRelation.to_rule_id == to_rule_id,
+                RuleRelation.kind == kind,
+            )
+        )
+        if existing is not None:
+            return existing
+        relation = RuleRelation(
+            from_rule_id=from_rule_id, to_rule_id=to_rule_id,
+            kind=kind, note=note or None,
+        )
+        session.add(relation)
+        await session.commit()
+        await session.refresh(relation)
+        return relation
+
+
+async def remove_rule_relation(user_id: int, relation_id: int) -> bool:
+    async with async_session() as session:
+        relation = await session.get(RuleRelation, relation_id)
+        if relation is None:
+            return False
+        if await _fetch_owned_rule(session, relation.from_rule_id, user_id) is None:
+            return False
+        await session.delete(relation)
+        await session.commit()
+        return True
+
+
+async def list_rule_relations(rule_ids: list[int]) -> dict[int, list[dict]]:
+    """Edges touching a batch of rules, keyed by rule id.
+
+    `co_surfaces` is reported from BOTH ends off a single stored row — it means
+    "these fail together", which is not a claim with a direction. The other two
+    are directional and are reported as stored, with `direction` naming which
+    end this rule is: an override read from the wrong end would invert what it
+    says.
+    """
+    if not rule_ids:
+        return {}
+    async with async_session() as session:
+        rows = (await session.execute(
+            select(RuleRelation).where(
+                (RuleRelation.from_rule_id.in_(rule_ids))
+                | (RuleRelation.to_rule_id.in_(rule_ids))
+            )
+        )).scalars().all()
+    out: dict[int, list[dict]] = {}
+    wanted = set(rule_ids)
+    for relation in rows:
+        if relation.from_rule_id in wanted:
+            out.setdefault(relation.from_rule_id, []).append({
+                "id": relation.id, "kind": relation.kind,
+                "rule_id": relation.to_rule_id,
+                "direction": "outgoing", "note": relation.note or "",
+            })
+        if relation.to_rule_id in wanted:
+            out.setdefault(relation.to_rule_id, []).append({
+                "id": relation.id, "kind": relation.kind,
+                "rule_id": relation.from_rule_id,
+                "direction": "incoming", "note": relation.note or "",
+            })
+    return out
+
+
 async def delete_rule(rule_id: int, user_id: int) -> None:
     async with async_session() as session:
         rule = await _fetch_owned_rule(session, rule_id, user_id)
@@ -533,7 +866,6 @@ 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
 
 
@@ -802,10 +1134,13 @@ async def get_applicable_rules(
         # Applicable rules (limit + 1 so we can detect truncation). Filter
         # in SQL so truncation reflects the post-suppression count, not the
         # raw subscription count.
+        # Selects the ENTITY, not a column list: rule_brief is the one place
+        # that decides which fields a surfaced rule carries, and a column list
+        # here would be a second such decision to keep in step. The row count
+        # is bounded by `limit`, so this is a listing, not a scan.
         rules_q = (
             select(
-                Rule.id, Rule.title, Rule.statement,
-                RulebookTopic.id.label("topic_id"),
+                Rule,
                 RulebookTopic.title.label("topic_title"),
                 Rulebook.id.label("rulebook_id"),
                 Rulebook.title.label("rulebook_title"),
@@ -835,21 +1170,41 @@ async def get_applicable_rules(
             rules_q = rules_q.where(Rule.id.notin_(suppressed_rule_ids))
         if suppressed_topic_ids:
             rules_q = rules_q.where(Rule.topic_id.notin_(suppressed_topic_ids))
+        # TIER (milestone 307). always_on rules are resident, as every rule was
+        # before tiers existed. A conditional rule is REACHABLE, and reaches
+        # this project only when it is tagged to an area this project actually
+        # works in — a deterministic tag match, never a similarity score, so
+        # bindingness never depends on a ranking (D7).
+        #
+        # Applied in SQL rather than by filtering afterwards, so `limit` counts
+        # the rules that will actually be surfaced instead of counting rules
+        # that are about to be dropped.
+        project_area_ids = (await session.execute(
+            select(System.canonical_id).where(
+                System.project_id == project_id,
+                System.canonical_id.is_not(None),
+                System.deleted_at.is_(None),
+                System.status == "active",
+            ).distinct()
+        )).scalars().all()
+        reachable = select(rule_systems.c.rule_id).where(
+            rule_systems.c.canonical_id.in_(project_area_ids)
+        ) if project_area_ids else None
+        tier_clause = (Rule.tier == "always_on")
+        if reachable is not None:
+            tier_clause = or_(tier_clause, Rule.id.in_(reachable))
+        rules_q = rules_q.where(tier_clause)
         rule_rows = (await session.execute(rules_q)).all()
         truncated = len(rule_rows) > limit
         rules = [
-            {
-                "id": rid, "title": rtitle, "statement": stmt,
-                "topic_id": ti, "topic_title": tt,
-                "rulebook_id": rbi, "rulebook_title": rbt,
-            }
-            for rid, rtitle, stmt, ti, tt, rbi, rbt in rule_rows[:limit]
+            rule_brief(rule, topic_title=tt, rulebook_id=rbi, rulebook_title=rbt)
+            for rule, tt, rbi, rbt in rule_rows[:limit]
         ]
 
         # Project-scoped rules — verifies ownership via Project.user_id.
         from scribe.models.project import Project
         proj_rules_q = (
-            select(Rule.id, Rule.title, Rule.statement)
+            select(Rule)
             .join(Project, Rule.project_id == Project.id)
             .where(
                 Project.user_id == user_id,
@@ -859,11 +1214,39 @@ async def get_applicable_rules(
             )
             .order_by(Rule.order_index, Rule.title)
         )
+        if reachable is not None:
+            proj_rules_q = proj_rules_q.where(
+                or_(Rule.tier == "always_on", Rule.id.in_(reachable))
+            )
+        else:
+            proj_rules_q = proj_rules_q.where(Rule.tier == "always_on")
         proj_rule_rows = (await session.execute(proj_rules_q)).all()
-        project_rules = [
-            {"id": rid, "title": rtitle, "statement": stmt}
-            for rid, rtitle, stmt in proj_rule_rows
-        ]
+        project_rules = [rule_brief(rule) for (rule,) in proj_rule_rows]
+
+    # Edges travel with the rules they belong to (milestone 307).
+    #
+    # A co_surfaces partner that was not otherwise selected is ADDED, because a
+    # rule that arrives without the half it fails with is the failure the edge
+    # was created to prevent. Suppressions are passed as exclusions so an
+    # explicit mute still wins over an edge.
+    surfaced_ids = [r["id"] for r in rules] + [r["id"] for r in project_rules]
+    partners = await co_surfaced_partners(
+        user_id, surfaced_ids, exclude_ids=set(suppressed_rule_ids),
+    )
+    for partner in partners:
+        rules.append(rule_brief(partner, via="co_surfaces"))
+        surfaced_ids.append(partner.id)
+
+    # Relations on every surfaced rule, so a reader can see that an override
+    # exists rather than discovering the contradiction by acting on the wrong
+    # one. Areas too — they are why a conditional rule is here at all.
+    edges = await list_rule_relations(surfaced_ids)
+    areas = await list_rule_systems(surfaced_ids)
+    for brief in (*rules, *project_rules):
+        if edges.get(brief["id"]):
+            brief["relations"] = edges[brief["id"]]
+        if areas.get(brief["id"]):
+            brief["systems"] = areas[brief["id"]]
 
     return {
         "rules": rules,

src/scribe/services/systems.py

@@ -14,38 +14,99 @@ from scribe.models import async_session
 from scribe.models.note import Note
 from scribe.models.system import RecordSystem, System
 from scribe.services import access
+from scribe.services import canonical_systems as canonical_systems_svc
 
 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."),
-)
+def local_name_key(name: str) -> str:
+    """The within-project uniqueness key: case and spacing, nothing else.
+
+    Deliberately weaker than `canonical_slug`. This one answers "is this the
+    same System I already have here", where the operator's own spelling is the
+    thing being compared; the canonical slug answers "is this the same AREA as
+    some other project's System", where spelling is exactly what must be
+    ignored.
+    """
+    return " ".join(name.split()).lower()
+
+
+async def assess_system_name(user_id: int, project_id: int, name: str) -> dict:
+    """What BOTH doors must know before minting a System name (milestone 307).
+
+    Lived in the MCP tool alone until now, which is how the web UI shipped
+    without a gate the agent surface enforced (#2482). One service function, so
+    the two doors cannot answer the same question differently (rule 33).
+
+    Returns `{"duplicate": …|None, "canonical": …|None}`:
+
+    - `duplicate` — this project already has a System by that name. A hard stop
+      for the caller: a second one splits the area's records across two piles.
+    - `canonical` — the global catalog covers this area, with a `basis`.
+      `exact` is mechanical and safe to apply on the spot; `overlap` is a
+      judgment call and must be OFFERED, never applied. Neither ever blocks:
+      an unmatched name is a project-specific area, which is legitimate.
+
+    Fails open on both arms — a naming aid must never break a create.
+    """
+    out: dict = {"duplicate": None, "canonical": None}
+    key = local_name_key(name)
+    if not key:
+        return out
+    try:
+        for existing in await list_systems(user_id, project_id, include_archived=True):
+            if local_name_key(existing.name) == key:
+                out["duplicate"] = {"id": existing.id, "name": existing.name}
+                return out
+    except Exception:
+        logger.debug("system name assessment: local scan failed", exc_info=True)
+        return out
+    try:
+        exact = await canonical_systems_svc.find_by_name(name)
+        if exact is not None:
+            out["canonical"] = {
+                "id": exact.id, "name": exact.name, "basis": "exact",
+            }
+            return out
+        # No exact hit: fall back to the same overlap scoring the review
+        # surface uses, so a create-time offer and a later proposal never
+        # disagree about which area a name resembles.
+        near = await canonical_systems_svc.best_overlap(name)
+        if near is not None:
+            out["canonical"] = near
+    except Exception:
+        logger.debug("system name assessment: catalog lookup failed", exc_info=True)
+    return out
+
+
+async def standard_systems() -> list[tuple[str, str]]:
+    """The standard cross-project vocabulary (#2798) as (name, charter) pairs.
+
+    Reads the GLOBAL canonical catalog (milestone 307). This was a tuple
+    constant in this module until the catalog became a table: a constant
+    cannot be a foreign key, so nothing outside a project could reference an
+    area, and the list only ever applied on the inception-seed path — which is
+    how three spellings of "CI & Release" reached one instance anyway.
+    """
+    return [(entry.name, entry.description or "") for entry in
+            await canonical_systems_svc.list_canonical_systems()]
 
 
 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."""
+    the project's own judgment take it from there. [] without write access.
+
+    Seeded Systems are mapped to their catalog entry as they are created, so a
+    project born this way needs no reconciliation pass later."""
     if await list_systems(user_id, project_id, include_archived=True):
         return []
     out: list[System] = []
-    for index, (name, charter) in enumerate(STANDARD_SYSTEMS):
+    for index, entry in enumerate(await canonical_systems_svc.list_canonical_systems()):
         system = await create_system(
-            user_id, project_id, name, description=charter, order_index=index,
+            user_id, project_id, entry.name, description=entry.description,
+            order_index=index, canonical_id=entry.id,
         )
         if system is None:
             break
@@ -60,8 +121,14 @@ async def create_system(
     description: str | None = None,
     color: str | None = None,
     order_index: int = 0,
+    canonical_id: int | None = None,
 ) -> System | None:
-    """Create a System. None if the user can't write the project."""
+    """Create a System. None if the user can't write the project.
+
+    `canonical_id` maps the new System onto the global catalog; leaving it None
+    is fine — an unmapped System is fully usable, and the mapping can be
+    proposed later (services/canonical_systems.propose_mappings).
+    """
     if not await access.can_write_project(user_id, project_id):
         return None
     async with async_session() as session:
@@ -72,6 +139,7 @@ async def create_system(
             description=description,
             color=color,
             order_index=order_index,
+            canonical_id=canonical_id,
         )
         session.add(system)
         await session.commit()
@@ -110,6 +178,10 @@ async def list_systems(
 
 async def update_system(user_id: int, system_id: int, **fields: object) -> System | None:
     """Update a System if the user can write its project."""
+    # canonical_id is deliberately NOT settable here: canonical_systems.
+    # set_system_canonical is its single writer, because it also validates the
+    # catalog entry is live. Two entry points onto one column is the drift this
+    # table exists to end.
     allowed = {"name", "description", "color", "status", "order_index"}
     async with async_session() as session:
         system = await session.get(System, system_id)

tests/conftest.py

@@ -82,3 +82,24 @@ def _no_supersession():
     with patch("scribe.services.plugin_context.superseded_ids",
                AsyncMock(return_value=set())):
         yield
+
+
+@pytest.fixture(autouse=True)
+def _no_rule_arm():
+    """Stub the write-path hint's standing-RULES arm (milestone 307).
+
+    Autouse, and deliberately so. The arm calls semantic_search_rules, which
+    loads the embedding model — so every unrelated plugin-context test that
+    already stubs the NOTES search would otherwise pull a real model into a
+    unit test through the one arm it forgot to stub. The forty-odd existing
+    call sites should not each have to learn about a new arm.
+
+    The arm's own behaviour is covered where it belongs: the document shape in
+    tests/test_services_rule_embeddings.py, the surfacing rules against real
+    Postgres in tests/test_integration_rule_surfacing.py, and the hook's dedup
+    channel in tests/test_write_path_trigger.py. A test that wants the arm
+    live can re-patch it.
+    """
+    with patch("scribe.services.plugin_context.semantic_search_rules",
+               AsyncMock(return_value=[])):
+        yield

tests/helpers.py

@@ -132,7 +132,9 @@ def fake_milestone(**attrs) -> MagicMock:
 
 
 def fake_system(**attrs) -> MagicMock:
-    return _with_defaults({"id": 1, "name": "Reader", "project_id": 5}, attrs)
+    return _with_defaults(
+        {"id": 1, "name": "Reader", "project_id": 5, "canonical_id": None}, attrs,
+    )
 
 
 def fake_rulebook(**attrs) -> MagicMock:
@@ -151,8 +153,12 @@ def fake_topic(**attrs) -> MagicMock:
 
 def fake_rule(**attrs) -> MagicMock:
     return _with_defaults({
-        "id": 1, "topic_id": 10, "title": "dev is home",
+        "id": 1, "topic_id": 10, "project_id": None, "title": "dev is home",
         "statement": "Work directly on dev", "why": "", "how_to_apply": "",
+        # Named for the note-2109 reason the whole helper exists: unnamed,
+        # `when_to_apply` and `arose_from_id` would be truthy MagicMocks and
+        # rule_brief would attach both keys on every stand-in.
+        "when_to_apply": None, "tier": "always_on", "arose_from_id": None,
         "order_index": 0, "created_at": _now(), "updated_at": _now(),
     }, attrs)
 

tests/test_inception.py

@@ -57,9 +57,22 @@ def test_normalize_choices_is_canonical_and_complete():
                                        "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)
+def test_standard_systems_vocabulary_reads_the_catalog_not_a_constant():
+    """The vocabulary moved from a module constant to the global catalog table
+    (milestone 307): a constant cannot be a foreign key, so nothing outside a
+    project could reference an area. The seed and the bootstrap ask must both
+    read the table, or the list they show and the list they mint diverge."""
+    import inspect
+
+    from scribe.services import systems as systems_svc
+
+    assert not hasattr(systems_svc, "STANDARD_SYSTEMS"), (
+        "the constant is gone — the catalog table is the single source"
+    )
+    source = inspect.getsource(systems_svc.seed_standard_systems)
+    assert "list_canonical_systems" in source
+    assert "canonical_id=entry.id" in source, (
+        "a seeded System must be mapped as it is created, or a project born "
+        "from the standard set still needs a reconciliation pass"
+    )
 

tests/test_integration_inception.py

@@ -13,6 +13,7 @@ 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 canonical_systems as canonical_svc
 from scribe.services import systems as systems_svc
 from tests.helpers import ensure_user
 
@@ -62,7 +63,11 @@ async def test_decide_applies_every_effect_and_records_last(seeded):
     })
     assert out["effects"]["excluded"] == [seeded["always"]]
     assert out["effects"]["subscribed"] == [seeded["other"]]
-    assert len(out["effects"]["systems_seeded"]) == len(systems_svc.STANDARD_SYSTEMS)
+    catalog = await canonical_svc.list_canonical_systems()
+    assert len(out["effects"]["systems_seeded"]) == len(catalog)
+    # Seeded Systems come out mapped, not needing a later reconciliation.
+    seeded_systems = await systems_svc.list_systems(owner, pid)
+    assert all(s.canonical_id is not None for s in seeded_systems)
 
     # The exclusion is total: the project's always-on set is empty, the
     # departure is named, the subscription binds.
@@ -81,7 +86,7 @@ async def test_decide_applies_every_effect_and_records_last(seeded):
     # 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)
+    assert len(await systems_svc.list_systems(owner, pid)) == len(catalog)
     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"]
 

tests/test_integration_rule_surfacing.py

@@ -0,0 +1,175 @@
+"""Real-Postgres tests for WHICH rules reach a session (milestone 307 step 5).
+
+What mocks can't prove, and what this milestone must not get wrong:
+
+1. **Nothing stops binding.** A rule with no tier, no areas and no edges
+   behaves exactly as it did before tiers existed. That is the one failure this
+   whole design must not produce, and it is asserted first.
+2. A conditional rule is invisible to a project that doesn't work in its area,
+   and arrives — binding, not suggested — to one that does.
+3. A `co_surfaces` partner arrives with its other half, which is the failure
+   that made merging rule 144 into rule 46 look like the only fix.
+4. An explicit suppression outranks an edge.
+"""
+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 canonical_systems as canonical_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 world():
+    """A project with TWO rulebooks, because the two payloads are different sets.
+
+    `list_always_on_rules` covers always-on rulebooks; `get_applicable_rules`
+    covers SUBSCRIBED ones. Conflating them is easy and would make these tests
+    assert nothing, so the fixture carries one of each and every test says
+    which payload it is about.
+    """
+    async with async_session() as s:
+        owner = await ensure_user(s, "surfacing_owner")
+        project = Project(user_id=owner.id, title="Surfacing 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")
+    async with async_session() as s:
+        rb = await s.get(Rulebook, always.id)
+        rb.always_on = True
+        await s.commit()
+    always_topic = await rulebooks_svc.create_topic(always.id, ids["owner"], "git")
+    await rulebooks_svc.create_rule(
+        always_topic.id, ids["owner"], "dev is home", "Work on dev.",
+    )
+
+    book = await rulebooks_svc.create_rulebook(ids["owner"], "Subscribed practices")
+    topic = await rulebooks_svc.create_topic(book.id, ids["owner"], "release")
+    plain = await rulebooks_svc.create_rule(
+        topic.id, ids["owner"], "Between batches, keep stacking", "Keep going.",
+    )
+    await rulebooks_svc.subscribe_project(
+        project_id=ids["pid"], rulebook_id=book.id, user_id=ids["owner"],
+    )
+    ids.update({
+        "always": always.id, "always_topic": always_topic.id,
+        "book": book.id, "topic": topic.id, "plain": plain.id,
+    })
+    return ids
+
+
+async def _titles(ids) -> set[str]:
+    applicable = await rulebooks_svc.get_applicable_rules(ids["pid"], ids["owner"])
+    return {r["title"] for r in applicable["rules"]}
+
+
+@pytest.mark.integration
+async def test_a_rule_with_no_tier_no_areas_and_no_edges_binds_exactly_as_before(world):
+    """THE compatibility guarantee. An install upgrades and every rule it
+    already had keeps arriving — no tier set, no areas, no edges, still bound.
+    Getting this wrong would silently stop enforcing rules people rely on,
+    which is worse than any amount of payload bloat."""
+    always_on = await rulebooks_svc.list_always_on_rules(world["owner"])
+    assert "dev is home" in {r.title for r in always_on}
+    assert "Between batches, keep stacking" in await _titles(world)
+
+
+@pytest.mark.integration
+async def test_a_conditional_rule_is_reachable_not_resident(world):
+    """It leaves the session-start payload entirely — that is the point of the
+    tier — and it does NOT reach a project with no matching area."""
+    # In the ALWAYS-ON book: the tier alone keeps it out of the session-start
+    # payload, which is the whole point of the tier.
+    resident = await rulebooks_svc.create_rule(
+        world["always_topic"], world["owner"], "Release tagging", "Derive the tag.",
+        when_to_apply="when cutting a release", tier="conditional",
+    )
+    assert resident.tier == "conditional"
+    always_on = await rulebooks_svc.list_always_on_rules(world["owner"])
+    assert "Release tagging" not in {r.title for r in always_on}
+
+    # In the SUBSCRIBED book, untagged: the project has no area to reach it by,
+    # so it stays out of the project payload too. Absent for a DIFFERENT reason
+    # than above, which is why both are asserted.
+    await rulebooks_svc.create_rule(
+        world["topic"], world["owner"], "Untagged conditional", "No area yet.",
+        when_to_apply="sometime", tier="conditional",
+    )
+    assert "Untagged conditional" not in await _titles(world)
+
+
+@pytest.mark.integration
+async def test_a_conditional_rule_binds_a_project_that_works_in_its_area(world):
+    """The payoff: the tag match carries it in deterministically. The project
+    reaches the area through its own System's canonical_id — its local NAME is
+    irrelevant, which is the whole reason the catalog exists."""
+    area = await canonical_svc.find_by_name("CI & Release")
+    assert area is not None, "migration 0087 seeds the standard vocabulary"
+
+    rule = await rulebooks_svc.create_rule(
+        world["topic"], world["owner"], "Release tagging", "Derive the tag.",
+        when_to_apply="when cutting a release", tier="conditional",
+    )
+    await rulebooks_svc.set_rule_systems(rule.id, world["owner"], [area.id])
+
+    # Still absent: the project has no Systems at all yet.
+    assert "Release tagging" not in await _titles(world)
+
+    # The project names the area with its OWN word, mapped to the same canon.
+    local = await systems_svc.create_system(
+        world["owner"], world["pid"], "CI & runners", description="ours",
+    )
+    await canonical_svc.set_system_canonical(world["owner"], local.id, area.id)
+
+    surfaced = await rulebooks_svc.get_applicable_rules(world["pid"], world["owner"])
+    hit = [r for r in surfaced["rules"] if r["title"] == "Release tagging"]
+    assert hit, "a tagged conditional rule must bind a project working in that area"
+    assert [s["name"] for s in hit[0]["systems"]] == ["CI & Release"]
+
+
+@pytest.mark.integration
+async def test_co_surfaces_drags_in_the_half_that_would_have_been_missed(world):
+    """Rule 144 was split off rule 46 and folded back the same day because
+    "either rule could surface without the other". This is the edge that makes
+    that unnecessary: the partner arrives even though nothing else selected
+    it, and says why it is here."""
+    partner = await rulebooks_svc.create_rule(
+        world["topic"], world["owner"], "Version names are labels",
+        "A name decides nothing.",
+        when_to_apply="when naming a build", tier="conditional",
+    )
+    await rulebooks_svc.add_rule_relation(
+        world["owner"], world["plain"], partner.id, "co_surfaces",
+        note="they fail together",
+    )
+    surfaced = await rulebooks_svc.get_applicable_rules(world["pid"], world["owner"])
+    hit = [r for r in surfaced["rules"] if r["title"] == "Version names are labels"]
+    assert hit, "a co_surfaces partner must arrive with its other half"
+    assert hit[0]["via"] == "co_surfaces"
+
+
+@pytest.mark.integration
+async def test_a_suppression_outranks_an_edge(world):
+    """The edge says these belong together; the suppression says this project
+    does not want that one. An explicit decision beats an inferred one."""
+    partner = await rulebooks_svc.create_rule(
+        world["topic"], world["owner"], "Muted partner", "Should not arrive.",
+        tier="conditional",
+    )
+    await rulebooks_svc.add_rule_relation(
+        world["owner"], world["plain"], partner.id, "co_surfaces",
+    )
+    await rulebooks_svc.suppress_rule_for_project(
+        world["pid"], partner.id, world["owner"],
+    )
+    surfaced = await rulebooks_svc.get_applicable_rules(world["pid"], world["owner"])
+    assert "Muted partner" not in {r["title"] for r in surfaced["rules"]}

tests/test_mcp_tool_rulebooks.py

@@ -1,5 +1,5 @@
 """Tests for MCP rulebook tools — patches the service layer."""
-from unittest.mock import AsyncMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 from tests.helpers import FakeMCP, fake_rule, fake_rulebook, fake_topic
@@ -48,11 +48,25 @@ async def test_get_rulebook_raises_when_not_found():
             await get_rulebook(rulebook_id=999)
 
 
+def _plain_detail():
+    """Stub the rule_detail seam these tool tests are not about.
+
+    create/update/get_rule now return through services.rulebooks.rule_detail,
+    which reads the rule's areas and edges from the database. These are unit
+    tests with no database, and what they assert is that the TOOL forwards the
+    right arguments — so the seam is stubbed to the plain record, the same way
+    they already stub the create/update calls themselves.
+    """
+    async def _detail(_uid, rule, _system_ids=None):
+        return rule.to_dict()
+    return patch("scribe.mcp.tools.rulebooks.rulebooks_svc.rule_detail", _detail)
+
+
 @pytest.mark.asyncio
 async def test_create_rule_passes_required_fields():
     rule = fake_rule(id=100, title="r", statement="s", topic_id=10)
     mock = AsyncMock(return_value=rule)
-    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_rule", mock):
+    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_rule", mock), _plain_detail():
         from scribe.mcp.tools.rulebooks import create_rule
         await create_rule(
             topic_id=10, title="dev is home", statement="Work directly on dev",
@@ -84,7 +98,8 @@ async def test_create_rule_force_bypasses_duplicate_gate():
     find_mock = AsyncMock()
     with patch("scribe.mcp.tools.rulebooks.dedup_svc.find_duplicate_rule", find_mock), \
          patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_rule",
-               AsyncMock(return_value=fake_rule(id=5, title="r", statement="s", topic_id=10))):
+               AsyncMock(return_value=fake_rule(id=5, title="r", statement="s", topic_id=10))), \
+         _plain_detail():
         from scribe.mcp.tools.rulebooks import create_rule
         out = await create_rule(topic_id=10, title="dev is home", statement="x", force=True)
     assert out["id"] == 5
@@ -95,7 +110,7 @@ async def test_create_rule_force_bypasses_duplicate_gate():
 async def test_update_rule_only_sends_non_default_fields():
     rule = fake_rule(id=100, title="r", statement="s", topic_id=10)
     mock = AsyncMock(return_value=rule)
-    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.update_rule", mock):
+    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.update_rule", mock), _plain_detail():
         from scribe.mcp.tools.rulebooks import update_rule
         await update_rule(rule_id=1, statement="new statement")
     args, kwargs = mock.call_args
@@ -169,7 +184,7 @@ def test_register_attaches_all_sixteen_tools():
     mcp = FakeMCP()
 
     register(mcp)
-    assert len(mcp.names) == 24   # +exclude/include_always_on_rulebook (milestone 297)
+    assert len(mcp.names) == 26   # +relate_rules/unrelate_rules (milestone 307)
     # spot-check a few names
     assert "list_rulebooks" in mcp.names
     assert "create_rule" in mcp.names
@@ -239,7 +254,7 @@ async def test_update_rulebook_omits_always_on_when_none():
 async def test_create_project_rule_passes_required_fields():
     rule = fake_rule(id=100, title="r", statement="s", topic_id=10)
     mock = AsyncMock(return_value=rule)
-    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock):
+    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock), _plain_detail():
         from scribe.mcp.tools.rulebooks import create_project_rule
         await create_project_rule(
             project_id=42,
@@ -257,7 +272,7 @@ async def test_create_project_rule_passes_required_fields():
 async def test_create_project_rule_derives_title_from_statement():
     rule = fake_rule(id=100, title="r", statement="s", topic_id=10)
     mock = AsyncMock(return_value=rule)
-    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock):
+    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock), _plain_detail():
         from scribe.mcp.tools.rulebooks import create_project_rule
         await create_project_rule(
             project_id=42,
@@ -272,7 +287,7 @@ async def test_create_project_rule_derives_title_from_statement():
 async def test_create_project_rule_uses_explicit_title_when_given():
     rule = fake_rule(id=100, title="r", statement="s", topic_id=10)
     mock = AsyncMock(return_value=rule)
-    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock):
+    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock), _plain_detail():
         from scribe.mcp.tools.rulebooks import create_project_rule
         await create_project_rule(
             project_id=42,
@@ -325,3 +340,47 @@ async def test_unsuppress_topic_for_project_passes_through():
     kwargs = mock.call_args.kwargs
     assert kwargs == {"project_id": 3, "topic_id": 22, "user_id": 7}
     assert out == {"project_id": 3, "topic_id": 22, "suppressed": False}
+
+
+# ── Typed edges between rules (milestone 307) ───────────────────────────
+
+@pytest.mark.asyncio
+async def test_relate_rules_forwards_the_kind_and_the_why():
+    """The edge exists so a shape stops being merged into one row. The `note`
+    travels with it for the same reason a rule carries `why`: whoever later
+    decides whether the edge still holds needs the reasoning."""
+    relation = MagicMock()
+    relation.to_dict.return_value = {"id": 9, "kind": "co_surfaces"}
+    mock = AsyncMock(return_value=relation)
+    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.add_rule_relation", mock):
+        from scribe.mcp.tools.rulebooks import relate_rules
+        out = await relate_rules(
+            from_rule_id=46, to_rule_id=144, kind="co_surfaces",
+            note="a stale channel tag and an unparseable version both read as "
+                 "no update available",
+        )
+    assert out["id"] == 9
+    args = mock.call_args.args
+    assert args[0] == 7 and args[1] == 46 and args[2] == 144
+    assert args[3] == "co_surfaces"
+    assert "no update available" in args[4]
+
+
+@pytest.mark.asyncio
+async def test_relate_rules_raises_when_either_end_is_not_yours():
+    """The service returns None when it cannot see both rules — a one-sided
+    edge would surface a rule the caller has no business reading."""
+    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.add_rule_relation",
+               AsyncMock(return_value=None)):
+        from scribe.mcp.tools.rulebooks import relate_rules
+        with pytest.raises(ValueError, match="not found"):
+            await relate_rules(from_rule_id=1, to_rule_id=2, kind="overrides")
+
+
+@pytest.mark.asyncio
+async def test_unrelate_rules_raises_when_the_edge_is_gone():
+    with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.remove_rule_relation",
+               AsyncMock(return_value=False)):
+        from scribe.mcp.tools.rulebooks import unrelate_rules
+        with pytest.raises(ValueError, match="not found"):
+            await unrelate_rules(relation_id=99)

tests/test_mcp_tool_systems.py

@@ -5,26 +5,86 @@ import pytest
 from tests.helpers import fake_note, fake_system
 
 
+# The name assessment both doors run before minting (milestone 307). A test
+# that patches systems_svc wholesale must stub it, or the awaited MagicMock
+# raises — this shape is the "nothing matched" answer.
+_NO_MATCH = {"duplicate": None, "canonical": None}
+
+
 @pytest.mark.asyncio
 async def test_create_system_returns_dict():
     with patch("scribe.mcp.tools.systems.current_user_id", return_value=1), \
          patch("scribe.mcp.tools.systems.systems_svc") as svc:
+        svc.assess_system_name = AsyncMock(return_value=_NO_MATCH)
         svc.create_system = AsyncMock(return_value=fake_system(name="Reader"))
         from scribe.mcp.tools.systems import create_system
         result = await create_system(project_id=5, name="Reader", description="pdf reader")
     assert result["name"] == "Reader"
+    # An unmatched name is a project-specific area: created, no offer, no fuss.
+    assert "canonical_suggestion" not in result and "canonical_note" not in result
 
 
 @pytest.mark.asyncio
 async def test_create_system_no_access_raises():
     with patch("scribe.mcp.tools.systems.current_user_id", return_value=1), \
          patch("scribe.mcp.tools.systems.systems_svc") as svc:
+        svc.assess_system_name = AsyncMock(return_value=_NO_MATCH)
         svc.create_system = AsyncMock(return_value=None)
         from scribe.mcp.tools.systems import create_system
         with pytest.raises(ValueError):
             await create_system(project_id=5, name="Reader")
 
 
+@pytest.mark.asyncio
+async def test_create_system_applies_an_exact_area_and_offers_a_similar_one():
+    """The two bases must behave differently, and this is where it is decided.
+
+    `exact` differs from the catalog name only in spelling, so it is APPLIED —
+    that is the mechanical case the catalog exists to collapse. `overlap` is a
+    judgment call, so it is only OFFERED: applying it silently is how a
+    cross-project rule ends up surfacing in the wrong project.
+    """
+    from scribe.mcp.tools.systems import create_system
+
+    with patch("scribe.mcp.tools.systems.current_user_id", return_value=1), \
+         patch("scribe.mcp.tools.systems.systems_svc") as svc:
+        svc.assess_system_name = AsyncMock(return_value={
+            "duplicate": None,
+            "canonical": {"id": 3, "name": "CI & Release", "basis": "exact"},
+        })
+        svc.create_system = AsyncMock(return_value=fake_system(name="CI and Release"))
+        exact = await create_system(project_id=5, name="CI and Release")
+    assert svc.create_system.await_args.kwargs["canonical_id"] == 3
+    assert "canonical_note" in exact and "canonical_suggestion" not in exact
+
+    with patch("scribe.mcp.tools.systems.current_user_id", return_value=1), \
+         patch("scribe.mcp.tools.systems.systems_svc") as svc:
+        svc.assess_system_name = AsyncMock(return_value={
+            "duplicate": None,
+            "canonical": {"id": 3, "name": "CI & Release", "basis": "overlap", "score": 0.33},
+        })
+        svc.create_system = AsyncMock(return_value=fake_system(id=9, name="CI & runners"))
+        similar = await create_system(project_id=5, name="CI & runners")
+    assert svc.create_system.await_args.kwargs["canonical_id"] is None
+    assert similar["canonical_suggestion"]["id"] == 3
+    assert "map_system_to_canonical(9, 3)" in similar["canonical_suggestion"]["message"]
+
+
+@pytest.mark.asyncio
+async def test_create_system_duplicate_names_the_existing_one_and_creates_nothing():
+    from scribe.mcp.tools.systems import create_system
+    with patch("scribe.mcp.tools.systems.current_user_id", return_value=1), \
+         patch("scribe.mcp.tools.systems.systems_svc") as svc:
+        svc.assess_system_name = AsyncMock(return_value={
+            "duplicate": {"id": 4, "name": "Reader"}, "canonical": None,
+        })
+        svc.create_system = AsyncMock()
+        result = await create_system(project_id=5, name="reader")
+    assert result["duplicate"] is True and result["existing_id"] == 4
+    assert "Reader" in result["message"]
+    svc.create_system.assert_not_awaited()
+
+
 @pytest.mark.asyncio
 async def test_get_system_splits_records_by_kind():
     issue = MagicMock(); issue.to_dict.return_value = {"id": 10}; issue.task_kind = "issue"; issue.status = "todo"
@@ -113,6 +173,15 @@ async def test_untagged_hint_escalates_in_a_mature_zero_systems_project():
          patch("scribe.mcp.tools.systems.notes_svc") as notes:
         svc.list_systems = AsyncMock(return_value=[])
         notes.list_notes = AsyncMock(return_value=(recent, 282))
+        # The standard names come from the GLOBAL catalog now (milestone 307),
+        # not a module constant — so the ask reads them through the service.
+        # That the SEEDED vocabulary is these eight is migration 0087's
+        # business, asserted against a real database in the inception
+        # integration test; what belongs here is that whatever the catalog
+        # holds reaches the ask verbatim.
+        svc.standard_systems = AsyncMock(return_value=[
+            ("CI & Release", "..."), ("Auth & Access", "..."),
+        ])
         hint = await untagged_systems_hint(1, 5)
     assert "282 records" in hint
     assert "Fix scrape retry backoff" in hint      # the project's own evidence
@@ -126,6 +195,25 @@ async def test_untagged_hint_escalates_in_a_mature_zero_systems_project():
     assert "no Systems yet" not in hint
 
 
+@pytest.mark.asyncio
+async def test_bootstrap_ask_still_asks_when_the_catalog_is_unreachable():
+    """The standard names are an AID to the question, not the question. If the
+    catalog read fails (or an install has an empty one), the ask must still
+    carry the project's evidence and demand the same deliverable — degrading to
+    a weaker nudge is acceptable, going silent is not."""
+    from scribe.mcp.tools.systems import untagged_systems_hint
+    recent = [fake_note(title="Fix scrape retry backoff")]
+    with patch("scribe.mcp.tools.systems.systems_svc") as svc, \
+         patch("scribe.mcp.tools.systems.notes_svc") as notes:
+        svc.list_systems = AsyncMock(return_value=[])
+        notes.list_notes = AsyncMock(return_value=(recent, 282))
+        svc.standard_systems = AsyncMock(side_effect=RuntimeError("db down"))
+        hint = await untagged_systems_hint(1, 5)
+    assert hint is not None
+    assert "282 records" in hint and "create_system" in hint
+    assert "3-6" in hint and "without asking permission" in hint
+
+
 @pytest.mark.asyncio
 async def test_bootstrap_ask_stays_quiet_below_threshold_and_fails_open():
     from scribe.mcp.tools import systems as tools
@@ -155,33 +243,11 @@ async def test_populated_vocabulary_never_counts_records():
     notes.list_notes.assert_not_awaited()
 
 
-@pytest.mark.asyncio
-async def test_create_system_same_normalized_name_is_duplicate_gated():
-    existing = fake_system(id=7, name="Scrape Pipeline")
-    existing.id = 7
-    existing.name = "Scrape Pipeline"
-    with patch("scribe.mcp.tools.systems.current_user_id", return_value=1), \
-         patch("scribe.mcp.tools.systems.systems_svc") as svc:
-        svc.list_systems = AsyncMock(return_value=[existing])
-        svc.create_system = AsyncMock()
-        from scribe.mcp.tools.systems import create_system
-        result = await create_system(project_id=5, name="  scrape   pipeline ")
-    assert result["duplicate"] is True
-    assert result["existing_id"] == 7
-    svc.create_system.assert_not_awaited()
-
-
-@pytest.mark.asyncio
-async def test_create_system_distinct_name_passes_the_gate():
-    other = fake_system(id=7, name="Workers")
-    other.name = "Workers"
-    with patch("scribe.mcp.tools.systems.current_user_id", return_value=1), \
-         patch("scribe.mcp.tools.systems.systems_svc") as svc:
-        svc.list_systems = AsyncMock(return_value=[other])
-        svc.create_system = AsyncMock(return_value=fake_system(id=8, name="Exporter"))
-        from scribe.mcp.tools.systems import create_system
-        result = await create_system(project_id=5, name="Exporter")
-    assert result["name"] == "Exporter"
+# The name gate's own cases (case/whitespace normalisation, exact-over-overlap,
+# fail-open) moved to tests/test_services_systems.py with the logic itself —
+# services/systems.assess_system_name, so both doors share one answer (#2482).
+# What stays the TOOL's job — rendering a duplicate, applying an exact area,
+# offering an overlap — is covered at the top of this file.
 
 
 @pytest.mark.asyncio

tests/test_routes_rulebooks.py

@@ -44,7 +44,8 @@ def test_service_signatures_require_user_id():
         "create_rulebook", "list_rulebooks", "get_rulebook",
         "update_rulebook", "delete_rulebook", "find_rulebook_by_title",
         "create_topic", "list_topics", "get_topic", "update_topic", "delete_topic",
-        "create_rule", "create_project_rule",
+        "create_rule", "create_project_rule", "rule_detail",
+        "set_rule_systems", "add_rule_relation", "remove_rule_relation",
         "list_rules", "list_always_on_rules",
         "get_rule", "update_rule", "delete_rule",
         "subscribe_project", "unsubscribe_project", "get_applicable_rules",
@@ -117,5 +118,7 @@ def test_rule_and_subscription_handlers_callable():
     for name in (
         "list_rules", "create_rule", "get_rule", "update_rule", "delete_rule",
         "subscribe_project", "unsubscribe_project", "get_project_rules",
+        # The typed edges — both doors carry them (rule 33).
+        "relate_rules", "unrelate_rules",
     ):
         assert callable(getattr(rb_routes, name))

tests/test_services_canonical_systems.py

@@ -0,0 +1,64 @@
+"""The canonical-slug matcher — the line between what maps mechanically and
+what a human is asked to confirm (milestone 307, note 3026).
+
+These cases are the real drift found across the author's own instance: one area
+carrying three spellings, and two areas that LOOK alike and are not the same.
+Getting the boundary wrong in either direction is a silent failure — a missed
+mapping nobody thinks to make again, or a cross-project record surfacing in the
+wrong project.
+"""
+import pytest
+
+from scribe.services.canonical_systems import canonical_slug
+
+
+@pytest.mark.parametrize("name", ["CI & Release", "CI and Release", "CI & release",
+                                  "  ci   and   release  "])
+def test_spelling_variants_of_one_area_collapse_to_one_key(name):
+    """Case, spacing, punctuation and "&" vs "and" are not real differences.
+    All three of the first spellings were live in different projects at once."""
+    assert canonical_slug(name) == "ci-and-release"
+
+
+@pytest.mark.parametrize("name,expected", [
+    ("Auth & Access", "auth-and-access"),
+    ("Data Model & Storage", "data-model-and-storage"),
+    ("UI & Design", "ui-and-design"),
+    ("Background Jobs", "background-jobs"),
+    ("Observability", "observability"),
+])
+def test_the_seeded_vocabulary_slugs_match_the_migration(name, expected):
+    """Migration 0087 writes these slugs literally. If the function and the
+    migration disagree, every seeded entry becomes unreachable by exact match
+    and every mapping silently degrades to a proposal."""
+    assert canonical_slug(name) == expected
+
+
+@pytest.mark.parametrize("a,b", [
+    ("CI & Release", "CI & runners"),
+    ("Auth & Access", "Auth & Accounts"),
+    ("UI & Design", "Frontend (Vue app)"),
+    ("UI & Design", "Web Shell and Theme"),
+])
+def test_genuinely_different_names_do_not_collapse(a, b):
+    """These pairs may or may not be the same area — that is a judgment call,
+    so they must NOT map automatically. They reach the operator as proposals."""
+    assert canonical_slug(a) != canonical_slug(b)
+
+
+def test_a_nameless_system_yields_no_key():
+    """An empty slug is the one value callers must special-case: two unnameable
+    Systems must not map onto each other. Both propose_mappings and find_by_name
+    bail on a falsy slug for this reason."""
+    assert canonical_slug("") == ""
+    assert canonical_slug("   ") == ""
+    assert canonical_slug("---") == ""
+
+
+def test_a_punctuation_separator_is_not_read_as_the_word_and():
+    """"CI/Release" is a real spelling and it does NOT collapse onto
+    "CI & Release" — only "&" carries that meaning. It still reaches the
+    operator through the overlap path, where both words match; what it must not
+    do is map itself silently."""
+    assert canonical_slug("CI/Release") == "ci-release"
+    assert canonical_slug("CI/Release") != canonical_slug("CI & Release")

tests/test_services_rule_embeddings.py

@@ -0,0 +1,84 @@
+"""The document a rule is EMBEDDED as (milestone 307 step 4, note 3026).
+
+This shape is measured, not chosen. Note 2485 probed the live corpus and found
+the snippet was the only discriminative record in it — a 0.153 top-to-second
+gap against 0.010-0.023 for everything else — and that the cause was its shape:
+purpose stated twice in a short, single-topic document. These cases pin that
+recipe onto rules, and pin the exclusion that matters more than any of it.
+"""
+import pytest
+
+from scribe.services.embeddings import chunk_document, rule_document
+
+
+def test_the_trigger_appears_twice_which_is_what_makes_a_vector_sharp():
+    """Repetition of purpose + brevity is the measured cause of the snippet's
+    separation. The rule document reproduces it exactly: the trigger in the
+    title, and again as the body's first line."""
+    title, body = rule_document(
+        "Release — never without explicit request",
+        "Never cut a release without the operator explicitly asking.",
+        "before cutting any release",
+    )
+    assert title == "Release — never without explicit request — before cutting any release"
+    assert body.startswith("When to apply: before cutting any release")
+    assert "Never cut a release" in body
+
+
+def test_why_is_never_embedded():
+    """The exclusion this whole design turns on. `why` is dated incident
+    narrative — rule 46's runs to 4,300 characters — and long multi-topic prose
+    is what made sixteen dev-logs mutually indistinguishable: the average lands
+    on a centroid they all share. Adding it would not give the vector more to
+    work with; it would give every rule the SAME thing to work with.
+
+    rule_document takes no `why` parameter at all, which is the strongest form
+    of this guarantee: it cannot be passed in by a caller who means well.
+    """
+    import inspect
+
+    assert "why" not in inspect.signature(rule_document).parameters
+
+
+def test_a_rule_with_no_trigger_still_embeds_just_less_sharply():
+    """Every rule written before milestone 307 has no trigger. Degrading to
+    title + statement keeps them findable; it does NOT pad the document with
+    whatever text is lying around, which would be the tempting fix and the
+    wrong one."""
+    title, body = rule_document("dev is home", "Work directly on dev.", "")
+    assert title == "dev is home"
+    assert body == "Work directly on dev."
+    assert "When to apply" not in body
+
+
+def test_an_empty_rule_yields_no_document_and_therefore_no_vector():
+    """Callers gate on falsiness to skip embedding — the same contract
+    chunk_document has, so an emptied record stops being findable by its old
+    content rather than keeping a stale vector."""
+    assert rule_document("", "", "") == (None, None)
+    assert chunk_document(*rule_document("", "", "")) == []
+
+
+def test_a_long_rule_chunks_and_every_chunk_carries_the_trigger():
+    """Rule 46's statement is ~3,600 characters across two headed sections.
+    The existing chunker splits it at headings and prefixes each chunk with the
+    title — which now CONTAINS the trigger, so each half stays anchored to what
+    the rule is for. This is why splitting a merged rule costs nothing at
+    retrieval time."""
+    statement = (
+        "## The tags\n\n" + ("Four tags, four jobs. " * 60)
+        + "\n\n## The artifact's own version\n\n" + ("Two version values. " * 60)
+    )
+    title, body = rule_document("Versioning", statement, "when cutting a release")
+    chunks = chunk_document(title, body)
+    assert len(chunks) > 1
+    assert all("when cutting a release" in chunk for chunk in chunks)
+
+
+@pytest.mark.parametrize("trigger,expected_title", [
+    ("before any git push", "dev is home — before any git push"),
+    ("  before any git push  ", "dev is home — before any git push"),
+])
+def test_the_trigger_is_trimmed_before_it_reaches_the_vector(trigger, expected_title):
+    title, _ = rule_document("dev is home", "Work on dev.", trigger)
+    assert title == expected_title

tests/test_services_rulebooks.py

@@ -2,6 +2,7 @@
 
 Mirrors the pattern in tests/test_events_service.py.
 """
+from datetime import datetime, timezone
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
@@ -197,6 +198,25 @@ def _empty():
     return r
 
 
+def _no_edges():
+    """Silence the three post-query lookups get_applicable_rules now makes.
+
+    They are separate service functions with their own coverage (and the real
+    wiring is proven against Postgres in test_integration_rule_surfacing), so
+    stubbing them here keeps each of these tests about the one projection it
+    was written to check — rather than about the order a mocked session's
+    execute() calls happen to arrive in.
+    """
+    return (
+        patch("scribe.services.rulebooks.co_surfaced_partners",
+              AsyncMock(return_value=[])),
+        patch("scribe.services.rulebooks.list_rule_relations",
+              AsyncMock(return_value={})),
+        patch("scribe.services.rulebooks.list_rule_systems",
+              AsyncMock(return_value={})),
+    )
+
+
 @pytest.mark.asyncio
 async def test_get_applicable_rules_returns_shape():
     """get_applicable_rules returns the full projection — including the
@@ -206,16 +226,20 @@ async def test_get_applicable_rules_returns_shape():
     sub_result.all.return_value = [(1, "FabledSword family")]
     rules_result = MagicMock()
     rules_result.all.return_value = [
-        # (rule_id, title, statement, topic_id, topic_title, rulebook_id, rulebook_title)
-        (i, f"Rule {i}", f"Statement {i}", 2, "git-workflow", 1, "FabledSword family")
+        # The query selects the ENTITY plus three labels, so rule_brief stays
+        # the one place deciding what a surfaced rule carries (note 3026).
+        (fake_rule(id=i, title=f"Rule {i}", statement=f"Statement {i}", topic_id=2),
+         "git-workflow", 1, "FabledSword family")
         for i in range(50)
     ]
-    # Execute order: sub_q, suppressed_rules_q, suppressed_topics_q, rules_q, proj_rules_q
+    # Execute order: sub_q, suppressed_rules_q, suppressed_topics_q,
+    # project-areas_q (milestone 307), rules_q, proj_rules_q
     mock_session.execute = AsyncMock(side_effect=[
-        sub_result, _empty(), _empty(), rules_result, _empty(),
+        sub_result, _empty(), _empty(), _empty(), rules_result, _empty(),
     ])
 
-    with patch("scribe.services.rulebooks.async_session") as mock_cls:
+    _p1, _p2, _p3 = _no_edges()
+    with patch("scribe.services.rulebooks.async_session") as mock_cls, _p1, _p2, _p3:
         mock_cls.return_value = mock_session
         from scribe.services.rulebooks import get_applicable_rules
         result = await get_applicable_rules(project_id=3, user_id=7, limit=50)
@@ -244,13 +268,14 @@ async def test_get_applicable_rules_truncates_when_over_limit():
     sub_result.all.return_value = []
     rules_result = MagicMock()
     rules_result.all.return_value = [
-        (i, f"r{i}", "stmt", 2, "topic", 1, "rb") for i in range(51)
+        (fake_rule(id=i, title=f"r{i}"), "topic", 1, "rb") for i in range(51)
     ]
     mock_session.execute = AsyncMock(side_effect=[
-        sub_result, _empty(), _empty(), rules_result, _empty(),
+        sub_result, _empty(), _empty(), _empty(), rules_result, _empty(),
     ])
 
-    with patch("scribe.services.rulebooks.async_session") as mock_cls:
+    _p1, _p2, _p3 = _no_edges()
+    with patch("scribe.services.rulebooks.async_session") as mock_cls, _p1, _p2, _p3:
         mock_cls.return_value = mock_session
         from scribe.services.rulebooks import get_applicable_rules
         result = await get_applicable_rules(project_id=3, user_id=7, limit=50)
@@ -265,14 +290,17 @@ async def test_get_applicable_rules_includes_project_scoped_rules():
     mock_session = make_mock_session()
     proj_rules_result = MagicMock()
     proj_rules_result.all.return_value = [
-        (100, "Use alembic", "Always run migrations via alembic, never raw SQL."),
-        (101, "PR-bound", "Land schema changes in their own PR."),
+        (fake_rule(id=100, topic_id=None, project_id=3, title="Use alembic",
+                   statement="Always run migrations via alembic, never raw SQL."),),
+        (fake_rule(id=101, topic_id=None, project_id=3, title="PR-bound",
+                   statement="Land schema changes in their own PR."),),
     ]
     mock_session.execute = AsyncMock(side_effect=[
-        _empty(), _empty(), _empty(), _empty(), proj_rules_result,
+        _empty(), _empty(), _empty(), _empty(), _empty(), proj_rules_result,
     ])
 
-    with patch("scribe.services.rulebooks.async_session") as mock_cls:
+    _p1, _p2, _p3 = _no_edges()
+    with patch("scribe.services.rulebooks.async_session") as mock_cls, _p1, _p2, _p3:
         mock_cls.return_value = mock_session
         from scribe.services.rulebooks import get_applicable_rules
         result = await get_applicable_rules(project_id=3, user_id=7)
@@ -298,10 +326,14 @@ async def test_get_applicable_rules_surfaces_suppressed_with_context():
         (22, "design-system", 1, "FabledSword family"),
     ]
     mock_session.execute = AsyncMock(side_effect=[
-        _empty(), suppressed_rules_result, suppressed_topics_result, _empty(), _empty(),
+        # sub_q, suppressed_rules_q, suppressed_topics_q, project-areas_q,
+        # rules_q, proj_rules_q
+        _empty(), suppressed_rules_result, suppressed_topics_result,
+        _empty(), _empty(), _empty(),
     ])
 
-    with patch("scribe.services.rulebooks.async_session") as mock_cls:
+    _p1, _p2, _p3 = _no_edges()
+    with patch("scribe.services.rulebooks.async_session") as mock_cls, _p1, _p2, _p3:
         mock_cls.return_value = mock_session
         from scribe.services.rulebooks import get_applicable_rules
         result = await get_applicable_rules(project_id=3, user_id=7)
@@ -311,3 +343,52 @@ async def test_get_applicable_rules_surfaces_suppressed_with_context():
     assert result["suppressed_rules"][0]["rulebook_title"] == "FabledSword family"
     assert len(result["suppressed_topics"]) == 1
     assert result["suppressed_topics"][0]["title"] == "design-system"
+
+
+# ── rule_brief + tier (milestone 307) ───────────────────────────────────
+
+def test_rule_brief_carries_age_but_not_the_deep_fields():
+    """The shape a SURFACED rule takes, and the reason it exists.
+
+    There were three hand-written copies of this dict and they had already
+    diverged — none carried the timestamps the model has always held, which is
+    why a rule written before the capability it duplicates was
+    indistinguishable at read time from one still doing work (note 3026).
+    """
+    from scribe.services.rulebooks import rule_brief
+
+    out = rule_brief(fake_rule(
+        when_to_apply="before any git push",
+        updated_at=datetime(2026, 6, 1, 14, 30, tzinfo=timezone.utc),
+    ))
+    assert out["when_to_apply"] == "before any git push"
+    assert out["tier"] == "always_on"
+    # A DATE, not a stamp: the question is "how old is this", and a full ISO
+    # string across the always-on set is ~2k characters of payload.
+    assert out["updated_at"] == "2026-06-01"
+    # The depth stays with get_rule — putting it in every listing is the bloat
+    # this milestone is about.
+    assert "why" not in out and "how_to_apply" not in out
+
+
+def test_rule_brief_omits_keys_a_rule_has_no_value_for():
+    """#2483: a null key reads as a capability the record has and isn't using,
+    which is a different claim from not having one."""
+    from scribe.services.rulebooks import rule_brief
+
+    out = rule_brief(fake_rule())
+    assert "when_to_apply" not in out
+    assert "arose_from_id" not in out
+
+
+def test_an_unknown_tier_falls_back_to_binding():
+    """The asymmetry that decides the direction: a rule that preloads when it
+    needn't costs context; a rule that quietly stops preloading costs the
+    behaviour it was written for. So a typo binds."""
+    from scribe.services.rulebooks import _valid_tier
+
+    assert _valid_tier("conditional") == "conditional"
+    assert _valid_tier("always_on") == "always_on"
+    assert _valid_tier("Conditional") == "always_on"
+    assert _valid_tier("") == "always_on"
+    assert _valid_tier("occasionally") == "always_on"

tests/test_services_systems.py

@@ -59,3 +59,70 @@ async def test_count_open_issues_denied_returns_zero():
         from scribe.services.systems import count_open_issues
         result = await count_open_issues(user_id=1, project_id=5)
     assert result == 0
+
+
+# ── assess_system_name — the one gate both doors call (milestone 307) ──
+
+@pytest.mark.asyncio
+async def test_assess_matches_an_existing_system_on_case_and_spacing():
+    """The local gate compares the operator's own spelling: case and runs of
+    whitespace are not a different System. Anything stronger belongs to the
+    CANONICAL slug, which is a different question (is this the same AREA as
+    another project's System) with a different answer."""
+    existing = MagicMock()
+    existing.id, existing.name = 7, "Scrape Pipeline"
+    with patch("scribe.services.systems.list_systems", AsyncMock(return_value=[existing])):
+        from scribe.services.systems import assess_system_name
+        out = await assess_system_name(1, 5, "  scrape   pipeline ")
+    assert out["duplicate"] == {"id": 7, "name": "Scrape Pipeline"}
+    # A duplicate short-circuits: there is nothing to file when nothing is created.
+    assert out["canonical"] is None
+
+
+@pytest.mark.asyncio
+async def test_assess_prefers_an_exact_area_over_a_merely_similar_one():
+    from scribe.services.systems import assess_system_name
+    exact = MagicMock()
+    exact.id, exact.name = 3, "CI & Release"
+    with patch("scribe.services.systems.list_systems", AsyncMock(return_value=[])), \
+         patch("scribe.services.systems.canonical_systems_svc") as canon:
+        canon.find_by_name = AsyncMock(return_value=exact)
+        canon.best_overlap = AsyncMock()
+        out = await assess_system_name(1, 5, "CI and Release")
+    assert out["canonical"] == {"id": 3, "name": "CI & Release", "basis": "exact"}
+    # An exact hit is the answer — no need to go looking for a lesser one.
+    canon.best_overlap.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_assess_falls_back_to_overlap_and_never_invents_a_match():
+    from scribe.services.systems import assess_system_name
+    near = {"id": 3, "name": "CI & Release", "basis": "overlap", "score": 0.33}
+    with patch("scribe.services.systems.list_systems", AsyncMock(return_value=[])), \
+         patch("scribe.services.systems.canonical_systems_svc") as canon:
+        canon.find_by_name = AsyncMock(return_value=None)
+        canon.best_overlap = AsyncMock(return_value=near)
+        assert (await assess_system_name(1, 5, "CI & runners"))["canonical"] == near
+        canon.best_overlap = AsyncMock(return_value=None)
+        # Nothing resembles it: a project-specific area, and silence is the
+        # right answer — unmapped is a valid resting state.
+        assert (await assess_system_name(1, 5, "Soundboard"))["canonical"] is None
+
+
+@pytest.mark.asyncio
+async def test_assess_fails_open_so_a_naming_aid_cannot_block_a_create():
+    """Both arms degrade to "no opinion" rather than raising. A create must
+    never fail because the catalog was unreachable."""
+    from scribe.services.systems import assess_system_name
+    with patch("scribe.services.systems.list_systems", AsyncMock(side_effect=RuntimeError("db down"))):
+        assert await assess_system_name(1, 5, "Reader") == {"duplicate": None, "canonical": None}
+    with patch("scribe.services.systems.list_systems", AsyncMock(return_value=[])), \
+         patch("scribe.services.systems.canonical_systems_svc") as canon:
+        canon.find_by_name = AsyncMock(side_effect=RuntimeError("db down"))
+        assert (await assess_system_name(1, 5, "Reader"))["canonical"] is None
+
+
+@pytest.mark.asyncio
+async def test_assess_says_nothing_about_a_nameless_system():
+    from scribe.services.systems import assess_system_name
+    assert await assess_system_name(1, 5, "   ") == {"duplicate": None, "canonical": None}

tests/test_write_path_trigger.py

@@ -1435,3 +1435,20 @@ async def test_the_write_time_divergence_check_is_named_in_band():
         out = await pc.build_write_path_hint(1, "x.py", code=REAL_CODE, stamp_shapes=[("sym", "f")])
     check.assert_not_awaited()
     assert out["divergence"] == []
+
+
+def test_hook_keeps_the_rule_channel_apart_from_the_other_three():
+    """Milestone 307's arm, pinned the way #2708's was.
+
+    Standing rules dedup on their OWN file and their OWN query parameter. One
+    shared channel is the bug #2708 already fixed once: a hint of one class
+    silencing a different class that had never been shown. A rule named early
+    must not be re-offered on every later write, and must not silence — or be
+    silenced by — a snippet suggestion.
+    """
+    src = HOOK.read_text()
+    assert ".rules.ids" in src                      # its own state file
+    assert "exclude_rule_ids=" in src               # its own query channel
+    assert "(.rule_ids // [])[]?" in src            # its own write-back
+    # And it rides the same request as the rest, not a second round trip.
+    assert "${rule_exclude_q}" in src