From 658348f208b858633f4da694d9bdcce99b149c6f Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Mon, 1 Jun 2026 00:56:08 -0400
Subject: [PATCH 1/3] feat(rules): always_on rulebook flag + Scribe-first
 prompt

Adds rulebooks.always_on (migration 0058) and a new list_always_on_rules
MCP tool so a session-start eager pull can fetch standing rules without
needing an active-project notion. Updates _INSTRUCTIONS so Claude calls
the new tool at session start and codifies engineering rules in Scribe
rather than CLAUDE.md / auto-memory.

Seeds FabledSword family rulebook to always_on=true on migrate, matching
its design role as the cross-project standards rulebook.

Frontend: badge in RulebookListPane for always-on rulebooks; toggle in
RulebookDetailPane header bound to a new toggleAlwaysOn store action.

This is S1+S2 of the rules-consolidation plan (Scribe task #508). S3
(project-scoped rules) and S4 (enter_project handshake) follow.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 alembic/versions/0058_rulebook_always_on.py   | 39 ++++++++++++++
 frontend/src/api/rulebooks.ts                 |  3 +-
 .../components/rules/RulebookDetailPane.vue   | 25 ++++++++-
 .../src/components/rules/RulebookListPane.vue | 13 ++++-
 frontend/src/stores/rulebooks.ts              | 10 +++-
 src/fabledassistant/mcp/server.py             | 23 +++++---
 src/fabledassistant/mcp/tools/rulebooks.py    | 38 ++++++++++++-
 src/fabledassistant/models/rulebook.py        |  6 ++-
 src/fabledassistant/routes/rulebooks.py       |  2 +-
 src/fabledassistant/services/rulebooks.py     | 29 +++++++++-
 tests/test_mcp_tool_rulebooks.py              | 53 ++++++++++++++++++-
 tests/test_routes_rulebooks.py                | 23 +++++++-
 12 files changed, 243 insertions(+), 21 deletions(-)
 create mode 100644 alembic/versions/0058_rulebook_always_on.py

diff --git a/alembic/versions/0058_rulebook_always_on.py b/alembic/versions/0058_rulebook_always_on.py
new file mode 100644
index 0000000..0607aae
--- /dev/null
+++ b/alembic/versions/0058_rulebook_always_on.py
@@ -0,0 +1,39 @@
+"""rulebook always_on flag
+
+Revision ID: 0058
+Revises: 0057
+Create Date: 2026-06-01
+
+Adds a boolean `always_on` to the `rulebooks` table. Rules from rulebooks
+flagged always_on are loaded at session start by the new
+`list_always_on_rules` MCP tool — they apply regardless of which project
+(if any) is in scope. Seeds the FabledSword family rulebook to always_on
+because that's the cross-project standards rulebook by design.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0058"
+down_revision = "0057"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "rulebooks",
+        sa.Column(
+            "always_on",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+    )
+    op.execute(
+        "UPDATE rulebooks SET always_on = TRUE WHERE title = 'FabledSword family'"
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("rulebooks", "always_on")
diff --git a/frontend/src/api/rulebooks.ts b/frontend/src/api/rulebooks.ts
index 77685a6..bb4bbfa 100644
--- a/frontend/src/api/rulebooks.ts
+++ b/frontend/src/api/rulebooks.ts
@@ -5,6 +5,7 @@ export interface Rulebook {
   owner_user_id: number;
   title: string;
   description: string;
+  always_on: boolean;
   created_at: string | null;
   updated_at: string | null;
 }
@@ -65,7 +66,7 @@ export async function createRulebook(data: { title: string; description?: string
   return apiPost("/api/rulebooks", data);
 }
 
-export async function updateRulebook(id: number, data: Partial<{ title: string; description: string }>): Promise<Rulebook> {
+export async function updateRulebook(id: number, data: Partial<{ title: string; description: string; always_on: boolean }>): Promise<Rulebook> {
   return apiPatch(`/api/rulebooks/${id}`, data);
 }
 
diff --git a/frontend/src/components/rules/RulebookDetailPane.vue b/frontend/src/components/rules/RulebookDetailPane.vue
index 56be664..ab69d29 100644
--- a/frontend/src/components/rules/RulebookDetailPane.vue
+++ b/frontend/src/components/rules/RulebookDetailPane.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref, onMounted, watch } from "vue";
+import { ref, computed, onMounted, watch } from "vue";
 import { useRulebooksStore } from "@/stores/rulebooks";
 import { apiGet } from "@/api/client";
 import {
@@ -18,6 +18,10 @@ const store = useRulebooksStore();
 const isCreating = ref(false);
 const newTitle = ref("");
 
+const currentRulebook = computed(() =>
+  store.rulebooks.find((rb) => rb.id === props.rulebookId),
+);
+
 interface ProjectLite { id: number; title: string }
 const projects = ref<ProjectLite[]>([]);
 // Map<project_id, Set<rulebook_id>>
@@ -68,7 +72,17 @@ watch(() => props.rulebookId, () => {/* re-render of isSubscribed from existing
 
 <template>
   <section class="pane">
-    <header><h2>Topics</h2></header>
+    <header>
+      <h2>Topics</h2>
+      <label v-if="currentRulebook" class="always-on-toggle" title="When on, rules from this rulebook load at session start regardless of project context">
+        <input
+          type="checkbox"
+          :checked="currentRulebook.always_on"
+          @change="store.toggleAlwaysOn(currentRulebook.id)"
+        />
+        <span>Always on</span>
+      </label>
+    </header>
     <ul>
       <li
         v-for="t in topics"
@@ -109,7 +123,14 @@ watch(() => props.rulebookId, () => {/* re-render of isSubscribed from existing
 
 <style scoped>
 .pane { background: var(--color-surface, #18181b); padding: 1rem; overflow-y: auto; }
+header { display: flex; align-items: center; justify-content: space-between; gap: 1rem; }
 header h2 { font-family: Fraunces, serif; font-style: italic; margin: 0 0 0.5rem 0; }
+.always-on-toggle {
+  display: flex; align-items: center; gap: 0.4rem;
+  font-size: 0.85rem; opacity: 0.85; cursor: pointer;
+  user-select: none;
+}
+.always-on-toggle input { cursor: pointer; }
 ul { list-style: none; padding: 0; margin: 1rem 0; }
 li { padding: 0.5rem; cursor: pointer; border-radius: 6px; }
 li.active { background: var(--color-primary-bg, rgba(99,102,241,0.15)); }
diff --git a/frontend/src/components/rules/RulebookListPane.vue b/frontend/src/components/rules/RulebookListPane.vue
index 33f8657..09e4f7e 100644
--- a/frontend/src/components/rules/RulebookListPane.vue
+++ b/frontend/src/components/rules/RulebookListPane.vue
@@ -31,6 +31,7 @@ async function submitNew() {
         @click="emit('select', rb.id)"
       >
         <span class="title">{{ rb.title }}</span>
+        <span v-if="rb.always_on" class="always-on-badge" title="Loaded at session start">always on</span>
       </li>
     </ul>
     <div class="new-rulebook">
@@ -50,9 +51,19 @@ async function submitNew() {
 .pane { background: var(--color-surface, #18181b); padding: 1rem; overflow-y: auto; }
 header h2 { font-family: Fraunces, serif; font-style: italic; margin: 0 0 0.5rem 0; }
 ul { list-style: none; padding: 0; margin: 1rem 0; }
-li { padding: 0.5rem; cursor: pointer; border-radius: 6px; }
+li { padding: 0.5rem; cursor: pointer; border-radius: 6px; display: flex; align-items: center; gap: 0.5rem; }
 li.active { background: var(--color-primary-bg, rgba(99,102,241,0.15)); }
 li:hover { background: var(--color-hover, rgba(255,255,255,0.05)); }
+.always-on-badge {
+  font-size: 0.7rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  padding: 0.1rem 0.4rem;
+  border-radius: 3px;
+  background: var(--color-accent, rgba(91,74,138,0.25));
+  color: var(--color-accent-fg, inherit);
+  margin-left: auto;
+}
 .new-rulebook { margin-top: 1rem; }
 .new-rulebook input {
   width: 100%; margin-bottom: 0.5rem;
diff --git a/frontend/src/stores/rulebooks.ts b/frontend/src/stores/rulebooks.ts
index 61d2b88..5bc1d7a 100644
--- a/frontend/src/stores/rulebooks.ts
+++ b/frontend/src/stores/rulebooks.ts
@@ -54,13 +54,19 @@ export const useRulebooksStore = defineStore("rulebooks", () => {
     return rb;
   }
 
-  async function updateRulebook(id: number, data: Partial<Pick<Rulebook, "title" | "description">>) {
+  async function updateRulebook(id: number, data: Partial<Pick<Rulebook, "title" | "description" | "always_on">>) {
     const rb = await api.updateRulebook(id, data);
     const idx = rulebooks.value.findIndex((r) => r.id === id);
     if (idx >= 0) rulebooks.value[idx] = rb;
     return rb;
   }
 
+  async function toggleAlwaysOn(id: number) {
+    const current = rulebooks.value.find((r) => r.id === id);
+    if (!current) return;
+    return updateRulebook(id, { always_on: !current.always_on });
+  }
+
   async function deleteRulebook(id: number) {
     await api.deleteRulebook(id);
     rulebooks.value = rulebooks.value.filter((r) => r.id !== id);
@@ -121,7 +127,7 @@ export const useRulebooksStore = defineStore("rulebooks", () => {
   return {
     rulebooks, topicsByRulebook, rulesByTopic, currentRule, loading,
     fetchRulebooks, fetchTopics, fetchRules, fetchRule,
-    createRulebook, updateRulebook, deleteRulebook,
+    createRulebook, updateRulebook, toggleAlwaysOn, deleteRulebook,
     createTopic, updateTopic, deleteTopic,
     createRule, updateRule, deleteRule,
   };
diff --git a/src/fabledassistant/mcp/server.py b/src/fabledassistant/mcp/server.py
index 67c8d33..6af1c0e 100644
--- a/src/fabledassistant/mcp/server.py
+++ b/src/fabledassistant/mcp/server.py
@@ -39,14 +39,21 @@ Mechanics:
   "not set".
 
 Scribe maintains a Rulebook system (Rulebook -> Topic -> Rule). Rules carry
-an actionable statement plus optional Why and How-to-apply context. When you
-start work on a project, get_project(id) returns applicable_rules (the rules
-from rulebooks the project subscribes to) and subscribed_rulebooks. Consult
-these before making decisions about workflow, conventions, or scope. Full
-text (Why / How-to-apply) is available via get_rule(id). You may create new
-rules via create_rule when you notice a pattern worth codifying — coordinate
-with the operator on whether it belongs in an existing rulebook+topic or a
-new one.
+an actionable statement plus optional Why and How-to-apply context. At the
+start of any session that touches Scribe, call list_always_on_rules() to
+load the standing rules — treat them as binding. When you also have a project
+in scope, get_project(id) returns applicable_rules (rules from rulebooks the
+project subscribes to) and subscribed_rulebooks; consult those too. Full text
+(Why / How-to-apply) is available via get_rule(id).
+
+Engineering and workflow rules live in Scribe. When you notice a pattern
+worth codifying, call create_rule. Do NOT add new engineering rules to
+CLAUDE.md or to ~/.claude/.../memory/feedback_*.md — those stores are
+reserved for facts about the user (preferences, role, communication style)
+and codebase onboarding pointers, respectively. Before creating a rule,
+call list_always_on_rules and list_rules(project_id=...) to avoid duplicates.
+Coordinate with the operator on whether a new rule belongs in an existing
+rulebook+topic or a new one.
 
 Plans are tasks with kind=plan, and Scribe is the canonical home for them.
 When you begin non-trivial work, call start_planning(project_id, title) FIRST —
diff --git a/src/fabledassistant/mcp/tools/rulebooks.py b/src/fabledassistant/mcp/tools/rulebooks.py
index 1f82a56..b4023be 100644
--- a/src/fabledassistant/mcp/tools/rulebooks.py
+++ b/src/fabledassistant/mcp/tools/rulebooks.py
@@ -54,14 +54,26 @@ async def create_rulebook(title: str, description: str = "") -> dict:
 
 async def update_rulebook(
     rulebook_id: int, title: str = "", description: str = "",
+    always_on: bool | None = None,
 ) -> dict:
-    """Update an existing rulebook. Only non-empty fields are changed."""
+    """Update an existing rulebook. Only non-empty fields are changed.
+
+    Args:
+        rulebook_id: Rulebook to update.
+        title: New title. Empty string leaves unchanged.
+        description: New description. Empty string leaves unchanged.
+        always_on: When True, rules in this rulebook are loaded at session
+            start by list_always_on_rules regardless of project context.
+            Pass None to leave unchanged.
+    """
     uid = current_user_id()
     fields: dict = {}
     if title:
         fields["title"] = title
     if description:
         fields["description"] = description
+    if always_on is not None:
+        fields["always_on"] = always_on
     rb = await rulebooks_svc.update_rulebook(rulebook_id, uid, **fields)
     if rb is None:
         raise ValueError(f"rulebook {rulebook_id} not found")
@@ -200,6 +212,28 @@ async def list_rules(
     }
 
 
+async def list_always_on_rules() -> dict:
+    """Return all rules from rulebooks flagged always_on for the current user.
+
+    Call this at session start. Treat the returned rules as binding for the
+    session — they apply regardless of which project (if any) is in scope.
+    Pair with get_project(id).applicable_rules when working on a specific
+    project to also load that project's subscription-derived rules.
+    """
+    uid = current_user_id()
+    rules = await rulebooks_svc.list_always_on_rules(uid)
+    return {
+        "rules": [
+            {
+                "id": r.id, "title": r.title, "statement": r.statement,
+                "topic_id": r.topic_id,
+            }
+            for r in rules
+        ],
+        "total": len(rules),
+    }
+
+
 async def get_rule(rule_id: int) -> dict:
     """Fetch a rule by id — full statement + why + how_to_apply."""
     uid = current_user_id()
@@ -302,7 +336,7 @@ 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, get_rule, create_rule, update_rule, delete_rule,
+        list_rules, list_always_on_rules, get_rule, create_rule, update_rule, delete_rule,
         subscribe_project_to_rulebook, unsubscribe_project_from_rulebook,
     ):
         mcp.tool(name=fn.__name__)(fn)
diff --git a/src/fabledassistant/models/rulebook.py b/src/fabledassistant/models/rulebook.py
index 16a93b0..adaedeb 100644
--- a/src/fabledassistant/models/rulebook.py
+++ b/src/fabledassistant/models/rulebook.py
@@ -1,6 +1,6 @@
 from datetime import datetime, timezone
 
-from sqlalchemy import BigInteger, Column, DateTime, ForeignKey, Integer, Table, Text, UniqueConstraint
+from sqlalchemy import BigInteger, Boolean, Column, DateTime, ForeignKey, Integer, Table, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column
 
 from fabledassistant.models import Base
@@ -16,6 +16,9 @@ class Rulebook(Base, SoftDeleteMixin):
     )
     title: Mapped[str] = mapped_column(Text)
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    always_on: Mapped[bool] = mapped_column(
+        Boolean, default=False, nullable=False, server_default="false"
+    )
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
     )
@@ -31,6 +34,7 @@ class Rulebook(Base, SoftDeleteMixin):
             "owner_user_id": self.owner_user_id,
             "title": self.title,
             "description": self.description or "",
+            "always_on": self.always_on,
             "created_at": self.created_at.isoformat() if self.created_at else None,
             "updated_at": self.updated_at.isoformat() if self.updated_at else None,
         }
diff --git a/src/fabledassistant/routes/rulebooks.py b/src/fabledassistant/routes/rulebooks.py
index c16b405..dc36ae9 100644
--- a/src/fabledassistant/routes/rulebooks.py
+++ b/src/fabledassistant/routes/rulebooks.py
@@ -55,7 +55,7 @@ async def get_rulebook(rulebook_id: int):
 @login_required
 async def update_rulebook(rulebook_id: int):
     data = await request.get_json() or {}
-    fields = {k: v for k, v in data.items() if k in ("title", "description")}
+    fields = {k: v for k, v in data.items() if k in ("title", "description", "always_on")}
     rb = await rulebooks_svc.update_rulebook(rulebook_id, _uid(), **fields)
     if rb is None:
         return jsonify({"error": "rulebook not found"}), 404
diff --git a/src/fabledassistant/services/rulebooks.py b/src/fabledassistant/services/rulebooks.py
index fa63f1e..0f4414d 100644
--- a/src/fabledassistant/services/rulebooks.py
+++ b/src/fabledassistant/services/rulebooks.py
@@ -72,7 +72,7 @@ async def update_rulebook(
         rb = result.scalar_one_or_none()
         if rb is None:
             return None
-        allowed = {"title", "description"}
+        allowed = {"title", "description", "always_on"}
         for key, value in fields.items():
             if key in allowed and value is not None:
                 setattr(rb, key, value)
@@ -305,6 +305,33 @@ async def list_rules(
         return list(result.scalars().all())
 
 
+async def list_always_on_rules(user_id: int, limit: int = 100) -> list[Rule]:
+    """Return all rules from rulebooks flagged always_on for the user.
+
+    Called by the MCP tool of the same name at session start to load the
+    standing rules that apply regardless of which project (if any) is in
+    scope. Ordering matches list_rules so results are stable across calls.
+    """
+    async with async_session() as session:
+        result = await session.execute(
+            select(Rule)
+            .join(RulebookTopic, Rule.topic_id == RulebookTopic.id)
+            .join(Rulebook, RulebookTopic.rulebook_id == Rulebook.id)
+            .where(
+                Rulebook.owner_user_id == user_id,
+                Rulebook.always_on.is_(True),
+                Rule.deleted_at.is_(None),
+                RulebookTopic.deleted_at.is_(None),
+                Rulebook.deleted_at.is_(None),
+            )
+            .order_by(
+                Rulebook.id, RulebookTopic.order_index, Rule.order_index, Rule.title,
+            )
+            .limit(limit)
+        )
+        return list(result.scalars().all())
+
+
 async def get_rule(rule_id: int, user_id: int) -> Optional[Rule]:
     async with async_session() as session:
         result = await session.execute(
diff --git a/tests/test_mcp_tool_rulebooks.py b/tests/test_mcp_tool_rulebooks.py
index 3c4ad08..c68fc72 100644
--- a/tests/test_mcp_tool_rulebooks.py
+++ b/tests/test_mcp_tool_rulebooks.py
@@ -179,8 +179,59 @@ def test_register_attaches_all_sixteen_tools():
             return decorator
 
     register(FakeMCP())
-    assert len(registered) == 16
+    assert len(registered) == 17
     # spot-check a few names
     assert "list_rulebooks" in registered
     assert "create_rule" in registered
     assert "subscribe_project_to_rulebook" in registered
+    assert "list_always_on_rules" in registered
+
+
+@pytest.mark.asyncio
+async def test_list_always_on_rules_returns_empty_when_no_always_on_rulebooks():
+    with patch(
+        "fabledassistant.mcp.tools.rulebooks.rulebooks_svc.list_always_on_rules",
+        AsyncMock(return_value=[]),
+    ):
+        from fabledassistant.mcp.tools.rulebooks import list_always_on_rules
+        out = await list_always_on_rules()
+    assert out == {"rules": [], "total": 0}
+
+
+@pytest.mark.asyncio
+async def test_list_always_on_rules_projects_each_rule():
+    rules = [_fake_rule(id=100), _fake_rule(id=101)]
+    with patch(
+        "fabledassistant.mcp.tools.rulebooks.rulebooks_svc.list_always_on_rules",
+        AsyncMock(return_value=rules),
+    ):
+        from fabledassistant.mcp.tools.rulebooks import list_always_on_rules
+        out = await list_always_on_rules()
+    assert out["total"] == 2
+    assert {r["id"] for r in out["rules"]} == {100, 101}
+    assert all("topic_id" in r for r in out["rules"])
+
+
+@pytest.mark.asyncio
+async def test_update_rulebook_forwards_always_on_when_set():
+    rb = _fake_rulebook(id=1, title="t")
+    mock = AsyncMock(return_value=rb)
+    with patch("fabledassistant.mcp.tools.rulebooks.rulebooks_svc.update_rulebook", mock):
+        from fabledassistant.mcp.tools.rulebooks import update_rulebook
+        await update_rulebook(rulebook_id=1, always_on=True)
+    kwargs = mock.call_args.kwargs
+    assert kwargs.get("always_on") is True
+    assert "title" not in kwargs
+    assert "description" not in kwargs
+
+
+@pytest.mark.asyncio
+async def test_update_rulebook_omits_always_on_when_none():
+    rb = _fake_rulebook(id=1, title="t")
+    mock = AsyncMock(return_value=rb)
+    with patch("fabledassistant.mcp.tools.rulebooks.rulebooks_svc.update_rulebook", mock):
+        from fabledassistant.mcp.tools.rulebooks import update_rulebook
+        await update_rulebook(rulebook_id=1, title="new title")
+    kwargs = mock.call_args.kwargs
+    assert "always_on" not in kwargs
+    assert kwargs["title"] == "new title"
diff --git a/tests/test_routes_rulebooks.py b/tests/test_routes_rulebooks.py
index 6f6fa0b..04bd6c1 100644
--- a/tests/test_routes_rulebooks.py
+++ b/tests/test_routes_rulebooks.py
@@ -44,13 +44,34 @@ 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", "list_rules", "get_rule", "update_rule", "delete_rule",
+        "create_rule", "list_rules", "list_always_on_rules",
+        "get_rule", "update_rule", "delete_rule",
         "subscribe_project", "unsubscribe_project", "get_applicable_rules",
     ):
         sig = inspect.signature(getattr(svc, fn_name))
         assert "user_id" in sig.parameters, f"{fn_name} missing user_id param"
 
 
+def test_rulebook_model_carries_always_on():
+    """Migration 0058 added rulebooks.always_on — verify the model declares it."""
+    from fabledassistant.models.rulebook import Rulebook
+    assert "always_on" in Rulebook.__table__.columns
+    col = Rulebook.__table__.columns["always_on"]
+    assert col.nullable is False
+
+
+def test_update_rulebook_route_accepts_always_on():
+    """PATCH /api/rulebooks/<id> must pass always_on through to the service.
+
+    The handler filters body keys against a whitelist; that whitelist needs to
+    include always_on or toggling from the UI silently drops the field.
+    """
+    import inspect as _inspect
+    from fabledassistant.routes import rulebooks as rb_routes
+    src = _inspect.getsource(rb_routes.update_rulebook)
+    assert "always_on" in src, "update_rulebook handler missing always_on in field whitelist"
+
+
 def test_rule_and_subscription_handlers_callable():
     from fabledassistant.routes import rulebooks as rb_routes
     for name in (
-- 
2.52.0


From 43a860c3ac59ff706e58b9707968791ac65eba95 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Mon, 1 Jun 2026 01:10:18 -0400
Subject: [PATCH 2/3] feat(rules): project-scoped rules (S3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rules can now belong to either a rulebook topic OR a single project,
enforced by a CHECK constraint (exactly-one of topic_id/project_id).
Adds the create_project_rule MCP tool + REST endpoint, surfaces
project-scoped rules in get_project/get_task/start_planning under a
new project_rules field, and adds a project Rules tab section with an
inline create form so the operator can author project rules from the
UI without rulebook ceremony.

- migration 0059: rules.project_id (FK projects ON DELETE CASCADE),
  topic_id now nullable, CHECK ck_rule_topic_xor_project, index on
  project_id
- model: Rule gains project_id; to_dict exposes it
- service: create_project_rule with project-ownership guard; list_rules
  with project_id filter UNIONs subscription-derived + project-scoped;
  get_applicable_rules adds a project_rules field; get_rule / update_rule
  / delete_rule fetch via a shared _fetch_owned_rule that handles both
  rulebook and project ownership paths
- trash: project delete cascades to project-scoped rules
- MCP: create_project_rule tool registered; _INSTRUCTIONS mentions both
  create_rule and create_project_rule paths
- REST: POST /api/projects/<id>/rules (statement required, title derived
  if omitted)
- frontend: Rule type gains nullable topic_id + project_id; createProjectRule
  client; ProjectRulesTab.vue gains a "Project rules" section with inline
  create form and per-rule expand/delete
- tests: register count → 18; create_project_rule unit tests (required
  fields, title derivation, explicit-title pass-through); applicable_rules
  shape tests now include project_rules; trash cascade test updated to
  expect 5 executions

S1+S2 (always_on flag + Scribe-first prompt) shipped in 658348f.
S4 (enter_project handshake) follows.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 alembic/versions/0059_rule_project_scope.py   |  49 +++++
 frontend/src/api/rulebooks.ts                 |  17 +-
 .../src/components/rules/ProjectRulesTab.vue  | 106 ++++++++++-
 src/fabledassistant/mcp/server.py             |  15 +-
 src/fabledassistant/mcp/tools/projects.py     |   1 +
 src/fabledassistant/mcp/tools/rulebooks.py    |  37 +++-
 src/fabledassistant/mcp/tools/tasks.py        |   1 +
 src/fabledassistant/models/rulebook.py        |  15 +-
 src/fabledassistant/routes/rulebooks.py       |  24 +++
 src/fabledassistant/services/planning.py      |   1 +
 src/fabledassistant/services/rulebooks.py     | 169 ++++++++++++++----
 src/fabledassistant/services/trash.py         |   2 +
 tests/test_mcp_tool_rulebooks.py              |  51 +++++-
 tests/test_routes_rulebooks.py                |  17 +-
 tests/test_services_rulebooks.py              |  37 +++-
 tests/test_services_trash.py                  |   8 +-
 16 files changed, 491 insertions(+), 59 deletions(-)
 create mode 100644 alembic/versions/0059_rule_project_scope.py

diff --git a/alembic/versions/0059_rule_project_scope.py b/alembic/versions/0059_rule_project_scope.py
new file mode 100644
index 0000000..04d49ae
--- /dev/null
+++ b/alembic/versions/0059_rule_project_scope.py
@@ -0,0 +1,49 @@
+"""project-scoped rules
+
+Revision ID: 0059
+Revises: 0058
+Create Date: 2026-06-01
+
+Rules can now belong to either a rulebook topic (cross-project standard) or
+a single project (project-scoped). Adds `rules.project_id`, makes `topic_id`
+nullable, and adds a CHECK constraint enforcing exactly-one. The previous
+unique constraint on (topic_id, title) still applies because PostgreSQL
+treats NULL as distinct — two project-scoped rules with the same title and
+NULL topic_id remain unique.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0059"
+down_revision = "0058"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "rules",
+        sa.Column(
+            "project_id",
+            sa.BigInteger(),
+            sa.ForeignKey("projects.id", ondelete="CASCADE"),
+            nullable=True,
+        ),
+    )
+    op.alter_column("rules", "topic_id", nullable=True)
+    op.create_index("ix_rules_project_id", "rules", ["project_id"])
+    op.create_check_constraint(
+        "ck_rule_topic_xor_project",
+        "rules",
+        "(topic_id IS NULL) <> (project_id IS NULL)",
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint("ck_rule_topic_xor_project", "rules", type_="check")
+    op.drop_index("ix_rules_project_id", table_name="rules")
+    # Any rule with NULL topic_id will block re-tightening. Operator must
+    # migrate or delete project-scoped rules before downgrading.
+    op.alter_column("rules", "topic_id", nullable=False)
+    op.drop_column("rules", "project_id")
diff --git a/frontend/src/api/rulebooks.ts b/frontend/src/api/rulebooks.ts
index bb4bbfa..d048290 100644
--- a/frontend/src/api/rulebooks.ts
+++ b/frontend/src/api/rulebooks.ts
@@ -22,7 +22,8 @@ export interface RulebookTopic {
 
 export interface Rule {
   id: number;
-  topic_id: number;
+  topic_id: number | null;
+  project_id: number | null;
   title: string;
   statement: string;
   why: string;
@@ -36,7 +37,7 @@ export interface RuleHeader {
   id: number;
   title: string;
   statement: string;
-  topic_id: number;
+  topic_id: number | null;
 }
 
 export interface ApplicableRules {
@@ -47,6 +48,11 @@ export interface ApplicableRules {
     topic_title: string;
     rulebook_title: string;
   }[];
+  project_rules: {
+    id: number;
+    title: string;
+    statement: string;
+  }[];
   truncated: boolean;
   subscribed_rulebooks: { id: number; title: string }[];
 }
@@ -134,3 +140,10 @@ export async function unsubscribeProject(projectId: number, rulebookId: number):
 export async function getProjectApplicableRules(projectId: number): Promise<ApplicableRules> {
   return apiGet(`/api/projects/${projectId}/rules`);
 }
+
+export async function createProjectRule(
+  projectId: number,
+  data: { statement: string; title?: string; why?: string; how_to_apply?: string },
+): Promise<Rule> {
+  return apiPost(`/api/projects/${projectId}/rules`, data);
+}
diff --git a/frontend/src/components/rules/ProjectRulesTab.vue b/frontend/src/components/rules/ProjectRulesTab.vue
index 955b58c..65e4f24 100644
--- a/frontend/src/components/rules/ProjectRulesTab.vue
+++ b/frontend/src/components/rules/ProjectRulesTab.vue
@@ -3,7 +3,7 @@ import { ref, onMounted, watch } from "vue";
 import { useRouter } from "vue-router";
 import {
   getProjectApplicableRules, subscribeProject, unsubscribeProject,
-  listRulebooks, getRule,
+  listRulebooks, getRule, createProjectRule, deleteRule,
 } from "@/api/rulebooks";
 import type { ApplicableRules, Rulebook } from "@/api/rulebooks";
 
@@ -16,6 +16,9 @@ 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: "" });
+
 async function load() {
   applicable.value = await getProjectApplicableRules(props.projectId);
 }
@@ -73,6 +76,26 @@ function rulebookIdForTitle(title: string): number | undefined {
   return applicable.value?.subscribed_rulebooks.find((rb) => rb.title === title)?.id;
 }
 
+async function submitProjectRule() {
+  const statement = newProjectRule.value.statement.trim();
+  if (!statement) return;
+  await createProjectRule(props.projectId, {
+    statement,
+    title: newProjectRule.value.title.trim() || undefined,
+    why: newProjectRule.value.why.trim() || undefined,
+    how_to_apply: newProjectRule.value.how_to_apply.trim() || undefined,
+  });
+  newProjectRule.value = { title: "", statement: "", why: "", how_to_apply: "" };
+  showProjectRuleForm.value = false;
+  await load();
+}
+
+async function removeProjectRule(ruleId: number) {
+  if (!confirm("Delete this project rule? It will move to the trash.")) return;
+  await deleteRule(ruleId);
+  await load();
+}
+
 onMounted(async () => {
   await load();
   await loadAllRulebooks();
@@ -111,6 +134,69 @@ watch(() => props.projectId, load);
       </div>
     </section>
 
+    <section class="project-rules">
+      <div class="section-head">
+        <h3>Project rules</h3>
+        <button
+          v-if="!showProjectRuleForm"
+          class="add"
+          @click="showProjectRuleForm = true"
+        >
+          + New project rule
+        </button>
+      </div>
+      <form v-if="showProjectRuleForm" class="new-rule-form" @submit.prevent="submitProjectRule">
+        <input
+          v-model="newProjectRule.title"
+          placeholder="Title (optional — derived from statement if blank)"
+        />
+        <textarea
+          v-model="newProjectRule.statement"
+          required
+          autofocus
+          placeholder="Statement (required) — the actionable instruction, 1-2 sentences"
+          rows="2"
+        ></textarea>
+        <textarea
+          v-model="newProjectRule.why"
+          placeholder="Why (optional) — the rationale"
+          rows="2"
+        ></textarea>
+        <textarea
+          v-model="newProjectRule.how_to_apply"
+          placeholder="How to apply (optional) — when / where it kicks in"
+          rows="2"
+        ></textarea>
+        <div class="form-buttons">
+          <button type="submit">Create</button>
+          <button type="button" @click="showProjectRuleForm = false">Cancel</button>
+        </div>
+      </form>
+      <ul v-if="applicable.project_rules && applicable.project_rules.length > 0" class="rule-list">
+        <li v-for="r in applicable.project_rules" :key="r.id" class="rule">
+          <div class="rule-head" @click="toggleRuleExpand(r.id)">
+            <span class="rule-title">{{ r.title }}</span>
+            <span class="rule-statement">{{ r.statement }}</span>
+          </div>
+          <div v-if="expandedRuleIds.has(r.id) && ruleDetails[r.id]" class="rule-detail">
+            <div v-if="ruleDetails[r.id].why">
+              <strong>Why:</strong> {{ ruleDetails[r.id].why }}
+            </div>
+            <div v-if="ruleDetails[r.id].how_to_apply">
+              <strong>How to apply:</strong> {{ ruleDetails[r.id].how_to_apply }}
+            </div>
+            <button class="delete-link" @click="removeProjectRule(r.id)">Delete</button>
+          </div>
+        </li>
+      </ul>
+      <p
+        v-else-if="!showProjectRuleForm"
+        class="empty"
+      >
+        No project-only rules yet.
+      </p>
+    </section>
+
     <section class="applicable">
       <h3>Applicable rules</h3>
       <p v-if="applicable.rules.length === 0" class="empty">
@@ -208,4 +294,22 @@ ul { list-style: none; padding: 0; margin: 0; }
 }
 .empty, .truncated { opacity: 0.7; font-style: italic; }
 .empty a { cursor: pointer; text-decoration: underline; }
+.project-rules { margin-top: 1.5rem; }
+.section-head { display: flex; justify-content: space-between; align-items: center; }
+.new-rule-form {
+  display: flex; flex-direction: column; gap: 0.5rem;
+  padding: 0.75rem; margin: 0.5rem 0;
+  background: var(--color-bg, #111113);
+  border: 1px solid var(--color-border, #2a2a2e); border-radius: 6px;
+}
+.new-rule-form input, .new-rule-form textarea {
+  background: var(--color-surface, #18181b); color: inherit;
+  border: 1px solid var(--color-border, #2a2a2e); border-radius: 6px;
+  padding: 0.5rem; font: inherit; resize: vertical;
+}
+.rule-list { margin-top: 0.5rem; }
+.delete-link {
+  background: none; border: none; cursor: pointer;
+  color: var(--color-destructive, #b85a4a); padding: 0.5rem 0 0 0;
+}
 </style>
diff --git a/src/fabledassistant/mcp/server.py b/src/fabledassistant/mcp/server.py
index 6af1c0e..3bac289 100644
--- a/src/fabledassistant/mcp/server.py
+++ b/src/fabledassistant/mcp/server.py
@@ -47,13 +47,14 @@ project subscribes to) and subscribed_rulebooks; consult those too. Full text
 (Why / How-to-apply) is available via get_rule(id).
 
 Engineering and workflow rules live in Scribe. When you notice a pattern
-worth codifying, call create_rule. Do NOT add new engineering rules to
-CLAUDE.md or to ~/.claude/.../memory/feedback_*.md — those stores are
-reserved for facts about the user (preferences, role, communication style)
-and codebase onboarding pointers, respectively. Before creating a rule,
-call list_always_on_rules and list_rules(project_id=...) to avoid duplicates.
-Coordinate with the operator on whether a new rule belongs in an existing
-rulebook+topic or a new one.
+worth codifying, call create_rule (cross-project, lands in a rulebook+topic)
+or create_project_rule (one project only, no rulebook ceremony). Do NOT add
+new engineering rules to CLAUDE.md or to ~/.claude/.../memory/feedback_*.md
+— those stores are reserved for facts about the user (preferences, role,
+communication style) and codebase onboarding pointers, respectively. Before
+creating a rule, call list_always_on_rules and list_rules(project_id=...) to
+avoid duplicates. Coordinate with the operator on whether a new rule belongs
+in a project, an existing rulebook+topic, or a new rulebook.
 
 Plans are tasks with kind=plan, and Scribe is the canonical home for them.
 When you begin non-trivial work, call start_planning(project_id, title) FIRST —
diff --git a/src/fabledassistant/mcp/tools/projects.py b/src/fabledassistant/mcp/tools/projects.py
index bb7c37f..c17fc63 100644
--- a/src/fabledassistant/mcp/tools/projects.py
+++ b/src/fabledassistant/mcp/tools/projects.py
@@ -55,6 +55,7 @@ async def get_project(project_id: int) -> dict:
     data["applicable_rules"] = applicable["rules"]
     data["applicable_rules_truncated"] = applicable["truncated"]
     data["subscribed_rulebooks"] = applicable["subscribed_rulebooks"]
+    data["project_rules"] = applicable.get("project_rules", [])
     return data
 
 
diff --git a/src/fabledassistant/mcp/tools/rulebooks.py b/src/fabledassistant/mcp/tools/rulebooks.py
index b4023be..809fc46 100644
--- a/src/fabledassistant/mcp/tools/rulebooks.py
+++ b/src/fabledassistant/mcp/tools/rulebooks.py
@@ -247,7 +247,7 @@ async def create_rule(
     topic_id: int, title: str, statement: str,
     why: str = "", how_to_apply: str = "", order_index: int = 0,
 ) -> dict:
-    """Create a new rule under a topic.
+    """Create a new rule under a topic (cross-project rulebook rule).
 
     Args:
         topic_id: The topic to attach the rule to.
@@ -256,6 +256,9 @@ async def create_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 topic (default 0).
+
+    For a rule that applies to a single project only, use create_project_rule
+    instead — no rulebook+topic ceremony required.
     """
     uid = current_user_id()
     rule = await rulebooks_svc.create_rule(
@@ -266,6 +269,35 @@ async def create_rule(
     return rule.to_dict()
 
 
+async def create_project_rule(
+    project_id: int, statement: str, title: str = "",
+    why: str = "", how_to_apply: str = "", order_index: int = 0,
+) -> dict:
+    """Create a rule scoped to a single project (no rulebook needed).
+
+    Use this when a rule only applies to one project — it bypasses the
+    Rulebook -> Topic -> Rule ceremony. The rule is returned in get_project's
+    applicable_rules (under project_rules) and in list_rules(project_id=...).
+
+    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.
+        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).
+    """
+    uid = current_user_id()
+    derived_title = title.strip() or statement.strip().split(".")[0][:50]
+    rule = await rulebooks_svc.create_project_rule(
+        project_id=project_id, user_id=uid,
+        title=derived_title, statement=statement,
+        why=why, how_to_apply=how_to_apply, order_index=order_index,
+    )
+    return rule.to_dict()
+
+
 async def update_rule(
     rule_id: int, title: str = "", statement: str = "",
     why: str = "", how_to_apply: str = "", order_index: int = -1,
@@ -336,7 +368,8 @@ 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, update_rule, delete_rule,
+        list_rules, list_always_on_rules, get_rule,
+        create_rule, create_project_rule, update_rule, delete_rule,
         subscribe_project_to_rulebook, unsubscribe_project_from_rulebook,
     ):
         mcp.tool(name=fn.__name__)(fn)
diff --git a/src/fabledassistant/mcp/tools/tasks.py b/src/fabledassistant/mcp/tools/tasks.py
index 4cfd4f1..ebe603f 100644
--- a/src/fabledassistant/mcp/tools/tasks.py
+++ b/src/fabledassistant/mcp/tools/tasks.py
@@ -82,6 +82,7 @@ async def get_task(task_id: int) -> dict:
         data["applicable_rules"] = applicable["rules"]
         data["subscribed_rulebooks"] = applicable["subscribed_rulebooks"]
         data["applicable_rules_truncated"] = applicable["truncated"]
+        data["project_rules"] = applicable.get("project_rules", [])
     return data
 
 
diff --git a/src/fabledassistant/models/rulebook.py b/src/fabledassistant/models/rulebook.py
index adaedeb..e382bb5 100644
--- a/src/fabledassistant/models/rulebook.py
+++ b/src/fabledassistant/models/rulebook.py
@@ -81,8 +81,18 @@ class Rule(Base, SoftDeleteMixin):
     )
 
     id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
-    topic_id: Mapped[int] = mapped_column(
-        BigInteger, ForeignKey("rulebook_topics.id", ondelete="CASCADE")
+    # Exactly one of topic_id / project_id is set — enforced by CHECK
+    # constraint ck_rule_topic_xor_project (migration 0059).
+    topic_id: Mapped[int | None] = mapped_column(
+        BigInteger,
+        ForeignKey("rulebook_topics.id", ondelete="CASCADE"),
+        nullable=True,
+    )
+    project_id: Mapped[int | None] = mapped_column(
+        BigInteger,
+        ForeignKey("projects.id", ondelete="CASCADE"),
+        nullable=True,
+        index=True,
     )
     title: Mapped[str] = mapped_column(Text)
     statement: Mapped[str] = mapped_column(Text)
@@ -102,6 +112,7 @@ class Rule(Base, SoftDeleteMixin):
         return {
             "id": self.id,
             "topic_id": self.topic_id,
+            "project_id": self.project_id,
             "title": self.title,
             "statement": self.statement,
             "why": self.why or "",
diff --git a/src/fabledassistant/routes/rulebooks.py b/src/fabledassistant/routes/rulebooks.py
index dc36ae9..8404072 100644
--- a/src/fabledassistant/routes/rulebooks.py
+++ b/src/fabledassistant/routes/rulebooks.py
@@ -239,3 +239,27 @@ async def get_project_rules(project_id: int):
         project_id=project_id, user_id=_uid(),
     )
     return jsonify(result)
+
+
+@rulebooks_bp.post("/projects/<int:project_id>/rules")
+@login_required
+async def create_project_rule(project_id: int):
+    """Create a rule scoped to a single project. Frontend fast path."""
+    data = await request.get_json() or {}
+    statement = (data.get("statement") or "").strip()
+    if not statement:
+        return jsonify({"error": "statement is required"}), 400
+    title = (data.get("title") or "").strip() or statement.split(".")[0][:50]
+    try:
+        rule = await rulebooks_svc.create_project_rule(
+            project_id=project_id,
+            user_id=_uid(),
+            title=title,
+            statement=statement,
+            why=data.get("why", ""),
+            how_to_apply=data.get("how_to_apply", ""),
+            order_index=data.get("order_index", 0),
+        )
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 404
+    return jsonify(rule.to_dict()), 201
diff --git a/src/fabledassistant/services/planning.py b/src/fabledassistant/services/planning.py
index 0bb9597..0385a42 100644
--- a/src/fabledassistant/services/planning.py
+++ b/src/fabledassistant/services/planning.py
@@ -58,6 +58,7 @@ async def start_planning(user_id: int, project_id: int, title: str) -> dict:
         "applicable_rules": applicable["rules"],
         "subscribed_rulebooks": applicable["subscribed_rulebooks"],
         "applicable_rules_truncated": applicable["truncated"],
+        "project_rules": applicable.get("project_rules", []),
         "project_goal": getattr(project, "goal", "") or "",
         "open_task_count": open_count,
     }
diff --git a/src/fabledassistant/services/rulebooks.py b/src/fabledassistant/services/rulebooks.py
index 0f4414d..8ea04e2 100644
--- a/src/fabledassistant/services/rulebooks.py
+++ b/src/fabledassistant/services/rulebooks.py
@@ -242,6 +242,20 @@ async def _assert_topic_owned(session, topic_id: int, user_id: int) -> None:
         raise ValueError(f"topic {topic_id} not found")
 
 
+async def _assert_project_owned(session, project_id: int, user_id: int) -> None:
+    """Raise ValueError if project doesn't exist or isn't owned by user."""
+    from fabledassistant.models.project import Project
+    result = await session.execute(
+        select(Project).where(
+            Project.id == project_id,
+            Project.user_id == user_id,
+            Project.deleted_at.is_(None),
+        )
+    )
+    if result.scalar_one_or_none() is None:
+        raise ValueError(f"project {project_id} not found")
+
+
 async def create_rule(
     topic_id: int, user_id: int, title: str, statement: str,
     why: str = "", how_to_apply: str = "", order_index: int = 0,
@@ -262,6 +276,32 @@ async def create_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,
+) -> Rule:
+    """Create a rule scoped to a single project (no rulebook ceremony).
+
+    Project-scoped rules apply only to the named project; they don't
+    propagate via rulebook subscriptions. Topic_id is left NULL — the
+    CHECK constraint enforces exactly-one of (topic_id, project_id).
+    """
+    async with async_session() as session:
+        await _assert_project_owned(session, project_id, user_id)
+        rule = Rule(
+            project_id=project_id,
+            title=title,
+            statement=statement,
+            why=why or None,
+            how_to_apply=how_to_apply or None,
+            order_index=order_index,
+        )
+        session.add(rule)
+        await session.commit()
+        await session.refresh(rule)
+        return rule
+
+
 async def list_rules(
     user_id: int,
     rulebook_id: int | None = None,
@@ -270,7 +310,12 @@ async def list_rules(
 ) -> list[Rule]:
     """List rules filtered by any of the three IDs. All filters are ownership-scoped.
 
-    project_id resolves rules through project_rulebook_subscriptions.
+    When project_id is set, the result includes both rulebook rules reached via
+    project_rulebook_subscriptions AND project-scoped rules (Rule.project_id).
+    When rulebook_id or topic_id is set, project-scoped rules are excluded by
+    construction (they have neither). With no filter, only rulebook rules are
+    returned — adding all of a user's project-scoped rules unprompted would
+    surprise existing callers.
     """
     from fabledassistant.models.rulebook import project_rulebook_subscriptions
 
@@ -302,7 +347,27 @@ async def list_rules(
             Rulebook.id, RulebookTopic.order_index, Rule.order_index, Rule.title,
         )
         result = await session.execute(stmt)
-        return list(result.scalars().all())
+        rulebook_rules = list(result.scalars().all())
+
+        if not project_id:
+            return rulebook_rules
+
+        # Project-scoped rules (topic_id IS NULL, project_id matches).
+        # Verifies ownership by joining Project on user_id.
+        from fabledassistant.models.project import Project
+        proj_stmt = (
+            select(Rule)
+            .join(Project, Rule.project_id == Project.id)
+            .where(
+                Project.user_id == user_id,
+                Rule.project_id == project_id,
+                Rule.deleted_at.is_(None),
+                Project.deleted_at.is_(None),
+            )
+            .order_by(Rule.order_index, Rule.title)
+        )
+        proj_result = await session.execute(proj_stmt)
+        return rulebook_rules + list(proj_result.scalars().all())
 
 
 async def list_always_on_rules(user_id: int, limit: int = 100) -> list[Rule]:
@@ -332,35 +397,51 @@ async def list_always_on_rules(user_id: int, limit: int = 100) -> list[Rule]:
         return list(result.scalars().all())
 
 
+async def _fetch_owned_rule(session, rule_id: int, user_id: int) -> Optional[Rule]:
+    """Fetch a rule by id, scoped to user owning either its rulebook
+    (via topic) or its project (via project_id). Honors soft-delete.
+    Returns None when not found or not owned.
+    """
+    from fabledassistant.models.project import Project
+
+    # Path A — rulebook rule.
+    rulebook_rule = (await session.execute(
+        select(Rule)
+        .join(RulebookTopic, Rule.topic_id == RulebookTopic.id)
+        .join(Rulebook, RulebookTopic.rulebook_id == Rulebook.id)
+        .where(
+            Rule.id == rule_id,
+            Rulebook.owner_user_id == user_id,
+            Rule.deleted_at.is_(None),
+            RulebookTopic.deleted_at.is_(None),
+            Rulebook.deleted_at.is_(None),
+        )
+    )).scalar_one_or_none()
+    if rulebook_rule is not None:
+        return rulebook_rule
+
+    # Path B — project-scoped rule.
+    project_rule = (await session.execute(
+        select(Rule)
+        .join(Project, Rule.project_id == Project.id)
+        .where(
+            Rule.id == rule_id,
+            Project.user_id == user_id,
+            Rule.deleted_at.is_(None),
+            Project.deleted_at.is_(None),
+        )
+    )).scalar_one_or_none()
+    return project_rule
+
+
 async def get_rule(rule_id: int, user_id: int) -> Optional[Rule]:
     async with async_session() as session:
-        result = await session.execute(
-            select(Rule)
-            .join(RulebookTopic, Rule.topic_id == RulebookTopic.id)
-            .join(Rulebook, RulebookTopic.rulebook_id == Rulebook.id)
-            .where(
-                Rule.id == rule_id,
-                Rulebook.owner_user_id == user_id,
-                Rule.deleted_at.is_(None),
-                RulebookTopic.deleted_at.is_(None),
-                Rulebook.deleted_at.is_(None),
-            )
-        )
-        return result.scalar_one_or_none()
+        return await _fetch_owned_rule(session, rule_id, user_id)
 
 
 async def update_rule(rule_id: int, user_id: int, **fields) -> Optional[Rule]:
     async with async_session() as session:
-        result = await session.execute(
-            select(Rule)
-            .join(RulebookTopic, Rule.topic_id == RulebookTopic.id)
-            .join(Rulebook, RulebookTopic.rulebook_id == Rulebook.id)
-            .where(
-                Rule.id == rule_id,
-                Rulebook.owner_user_id == user_id,
-            )
-        )
-        rule = result.scalar_one_or_none()
+        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"}
@@ -374,16 +455,7 @@ async def update_rule(rule_id: int, user_id: int, **fields) -> Optional[Rule]:
 
 async def delete_rule(rule_id: int, user_id: int) -> None:
     async with async_session() as session:
-        result = await session.execute(
-            select(Rule)
-            .join(RulebookTopic, Rule.topic_id == RulebookTopic.id)
-            .join(Rulebook, RulebookTopic.rulebook_id == Rulebook.id)
-            .where(
-                Rule.id == rule_id,
-                Rulebook.owner_user_id == user_id,
-            )
-        )
-        rule = result.scalar_one_or_none()
+        rule = await _fetch_owned_rule(session, rule_id, user_id)
         if rule is None:
             return
         await session.delete(rule)
@@ -434,14 +506,19 @@ async def unsubscribe_project(
 async def get_applicable_rules(
     project_id: int, user_id: int, limit: int = 50,
 ) -> dict:
-    """Return rules applicable to a project via its subscriptions.
+    """Return rules applicable to a project — both via rulebook subscriptions
+    and project-scoped rules (Rule.project_id matches).
 
     Shape:
         {
           "rules": [{id, title, statement, topic_title, rulebook_title}, ...],
+          "project_rules": [{id, title, statement}, ...],
           "truncated": bool,
           "subscribed_rulebooks": [{id, title}, ...]
         }
+
+    `rules` is the subscription-derived set (legacy shape preserved).
+    `project_rules` is the project-scoped set; empty list when none exist.
     """
     from fabledassistant.models.rulebook import project_rulebook_subscriptions
 
@@ -500,8 +577,28 @@ async def get_applicable_rules(
             for rid, rtitle, stmt, tt, rbt in rule_rows[:limit]
         ]
 
+        # Project-scoped rules — verifies ownership via Project.user_id.
+        from fabledassistant.models.project import Project
+        proj_rules_q = (
+            select(Rule.id, Rule.title, Rule.statement)
+            .join(Project, Rule.project_id == Project.id)
+            .where(
+                Project.user_id == user_id,
+                Rule.project_id == project_id,
+                Rule.deleted_at.is_(None),
+                Project.deleted_at.is_(None),
+            )
+            .order_by(Rule.order_index, Rule.title)
+        )
+        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
+        ]
+
     return {
         "rules": rules,
+        "project_rules": project_rules,
         "truncated": truncated,
         "subscribed_rulebooks": subscribed_rulebooks,
     }
diff --git a/src/fabledassistant/services/trash.py b/src/fabledassistant/services/trash.py
index e7dc658..30a9072 100644
--- a/src/fabledassistant/services/trash.py
+++ b/src/fabledassistant/services/trash.py
@@ -53,6 +53,8 @@ async def _cascade(session, user_id: int, etype: str, eid: int, batch: str, now)
     if etype == "project":
         await _set(session, Note, [Note.user_id == user_id, Note.project_id == eid], batch, now)
         await _set(session, Milestone, [Milestone.user_id == user_id, Milestone.project_id == eid], batch, now)
+        # Project-scoped rules cascade with the project they're attached to.
+        await _set(session, Rule, [Rule.project_id == eid], batch, now)
         await _set(session, Project, [Project.user_id == user_id, Project.id == eid], batch, now)
     elif etype == "milestone":
         await _set(session, Note, [Note.user_id == user_id, Note.milestone_id == eid], batch, now)
diff --git a/tests/test_mcp_tool_rulebooks.py b/tests/test_mcp_tool_rulebooks.py
index c68fc72..f2b3495 100644
--- a/tests/test_mcp_tool_rulebooks.py
+++ b/tests/test_mcp_tool_rulebooks.py
@@ -179,12 +179,13 @@ def test_register_attaches_all_sixteen_tools():
             return decorator
 
     register(FakeMCP())
-    assert len(registered) == 17
+    assert len(registered) == 18
     # spot-check a few names
     assert "list_rulebooks" in registered
     assert "create_rule" in registered
     assert "subscribe_project_to_rulebook" in registered
     assert "list_always_on_rules" in registered
+    assert "create_project_rule" in registered
 
 
 @pytest.mark.asyncio
@@ -235,3 +236,51 @@ async def test_update_rulebook_omits_always_on_when_none():
     kwargs = mock.call_args.kwargs
     assert "always_on" not in kwargs
     assert kwargs["title"] == "new title"
+
+
+@pytest.mark.asyncio
+async def test_create_project_rule_passes_required_fields():
+    rule = _fake_rule()
+    mock = AsyncMock(return_value=rule)
+    with patch("fabledassistant.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock):
+        from fabledassistant.mcp.tools.rulebooks import create_project_rule
+        await create_project_rule(
+            project_id=42,
+            statement="Always run migrations through alembic, not raw SQL.",
+            why="audit trail",
+        )
+    kwargs = mock.call_args.kwargs
+    assert kwargs["user_id"] == 7
+    assert kwargs["project_id"] == 42
+    assert kwargs["statement"].startswith("Always run migrations")
+    assert kwargs["why"] == "audit trail"
+
+
+@pytest.mark.asyncio
+async def test_create_project_rule_derives_title_from_statement():
+    rule = _fake_rule()
+    mock = AsyncMock(return_value=rule)
+    with patch("fabledassistant.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock):
+        from fabledassistant.mcp.tools.rulebooks import create_project_rule
+        await create_project_rule(
+            project_id=42,
+            statement="Avoid auto-generated docstrings. Reviewers find them noise.",
+        )
+    kwargs = mock.call_args.kwargs
+    # Title should be derived from the first sentence, capped at 50 chars
+    assert kwargs["title"] == "Avoid auto-generated docstrings"
+
+
+@pytest.mark.asyncio
+async def test_create_project_rule_uses_explicit_title_when_given():
+    rule = _fake_rule()
+    mock = AsyncMock(return_value=rule)
+    with patch("fabledassistant.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock):
+        from fabledassistant.mcp.tools.rulebooks import create_project_rule
+        await create_project_rule(
+            project_id=42,
+            statement="anything",
+            title="no auto-docstrings",
+        )
+    kwargs = mock.call_args.kwargs
+    assert kwargs["title"] == "no auto-docstrings"
diff --git a/tests/test_routes_rulebooks.py b/tests/test_routes_rulebooks.py
index 04bd6c1..891f95d 100644
--- a/tests/test_routes_rulebooks.py
+++ b/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", "list_rules", "list_always_on_rules",
+        "create_rule", "create_project_rule",
+        "list_rules", "list_always_on_rules",
         "get_rule", "update_rule", "delete_rule",
         "subscribe_project", "unsubscribe_project", "get_applicable_rules",
     ):
@@ -52,6 +53,20 @@ def test_service_signatures_require_user_id():
         assert "user_id" in sig.parameters, f"{fn_name} missing user_id param"
 
 
+def test_rule_model_carries_project_id_and_topic_id_nullable():
+    """Migration 0059 made topic_id nullable and added project_id."""
+    from fabledassistant.models.rulebook import Rule
+    assert "project_id" in Rule.__table__.columns
+    assert Rule.__table__.columns["topic_id"].nullable is True
+    assert Rule.__table__.columns["project_id"].nullable is True
+
+
+def test_create_project_rule_route_exists():
+    """POST /api/projects/<id>/rules — the frontend fast-path endpoint."""
+    from fabledassistant.routes import rulebooks as rb_routes
+    assert callable(getattr(rb_routes, "create_project_rule"))
+
+
 def test_rulebook_model_carries_always_on():
     """Migration 0058 added rulebooks.always_on — verify the model declares it."""
     from fabledassistant.models.rulebook import Rulebook
diff --git a/tests/test_services_rulebooks.py b/tests/test_services_rulebooks.py
index 05cf2ee..babed27 100644
--- a/tests/test_services_rulebooks.py
+++ b/tests/test_services_rulebooks.py
@@ -243,7 +243,7 @@ async def test_subscribe_project_requires_owned_rulebook():
 
 @pytest.mark.asyncio
 async def test_get_applicable_rules_returns_shape():
-    """get_applicable_rules returns {rules, truncated, subscribed_rulebooks}."""
+    """get_applicable_rules returns {rules, project_rules, truncated, subscribed_rulebooks}."""
     mock_session = _make_mock_session()
     sub_result = MagicMock()
     sub_result.all.return_value = [(1, "FabledSword family")]
@@ -252,7 +252,9 @@ async def test_get_applicable_rules_returns_shape():
         (i, f"Rule {i}", f"Statement {i}", "git-workflow", "FabledSword family")
         for i in range(50)
     ]
-    mock_session.execute = AsyncMock(side_effect=[sub_result, rules_result])
+    proj_rules_result = MagicMock()
+    proj_rules_result.all.return_value = []
+    mock_session.execute = AsyncMock(side_effect=[sub_result, rules_result, proj_rules_result])
 
     with patch("fabledassistant.services.rulebooks.async_session") as mock_cls:
         mock_cls.return_value = mock_session
@@ -260,10 +262,12 @@ async def test_get_applicable_rules_returns_shape():
         result = await get_applicable_rules(project_id=3, user_id=7, limit=50)
 
     assert "rules" in result
+    assert "project_rules" in result
     assert "truncated" in result
     assert "subscribed_rulebooks" in result
     assert result["subscribed_rulebooks"] == [{"id": 1, "title": "FabledSword family"}]
     assert len(result["rules"]) == 50
+    assert result["project_rules"] == []
     assert result["truncated"] is False  # exactly 50, not over
 
 
@@ -278,7 +282,9 @@ async def test_get_applicable_rules_truncates_when_over_limit():
     rules_result.all.return_value = [
         (i, f"r{i}", "stmt", "topic", "rb") for i in range(51)
     ]
-    mock_session.execute = AsyncMock(side_effect=[sub_result, rules_result])
+    proj_rules_result = MagicMock()
+    proj_rules_result.all.return_value = []
+    mock_session.execute = AsyncMock(side_effect=[sub_result, rules_result, proj_rules_result])
 
     with patch("fabledassistant.services.rulebooks.async_session") as mock_cls:
         mock_cls.return_value = mock_session
@@ -287,3 +293,28 @@ async def test_get_applicable_rules_truncates_when_over_limit():
 
     assert result["truncated"] is True
     assert len(result["rules"]) == 50
+
+
+@pytest.mark.asyncio
+async def test_get_applicable_rules_includes_project_scoped_rules():
+    """Project-scoped rules surface in the project_rules field."""
+    mock_session = _make_mock_session()
+    sub_result = MagicMock()
+    sub_result.all.return_value = []
+    rules_result = MagicMock()
+    rules_result.all.return_value = []
+    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."),
+    ]
+    mock_session.execute = AsyncMock(side_effect=[sub_result, rules_result, proj_rules_result])
+
+    with patch("fabledassistant.services.rulebooks.async_session") as mock_cls:
+        mock_cls.return_value = mock_session
+        from fabledassistant.services.rulebooks import get_applicable_rules
+        result = await get_applicable_rules(project_id=3, user_id=7)
+
+    assert len(result["project_rules"]) == 2
+    assert result["project_rules"][0]["title"] == "Use alembic"
+    assert result["project_rules"][1]["id"] == 101
diff --git a/tests/test_services_trash.py b/tests/test_services_trash.py
index 85aab2d..09af133 100644
--- a/tests/test_services_trash.py
+++ b/tests/test_services_trash.py
@@ -48,18 +48,18 @@ async def test_delete_returns_none_when_not_found():
 
 
 @pytest.mark.asyncio
-async def test_delete_project_cascades_three_tables():
+async def test_delete_project_cascades_to_notes_milestones_and_project_rules():
     session = _make_mock_session()
-    # exists-check + 3 cascade updates (notes, milestones, project)
+    # exists-check + 4 cascade updates (notes, milestones, project-scoped rules, project)
     session.execute = AsyncMock(side_effect=[
-        _exists_result(True), MagicMock(), MagicMock(), MagicMock(),
+        _exists_result(True), MagicMock(), MagicMock(), MagicMock(), MagicMock(),
     ])
     with patch("fabledassistant.services.trash.async_session") as cls:
         cls.return_value = session
         from fabledassistant.services.trash import delete
         batch = await delete(user_id=1, entity_type="project", entity_id=3)
     assert isinstance(batch, str)
-    assert session.execute.await_count == 4
+    assert session.execute.await_count == 5
 
 
 @pytest.mark.asyncio
-- 
2.52.0


From c5469214e39d83d72f10f3b797f6530ee5cb54de Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Mon, 1 Jun 2026 01:14:37 -0400
Subject: [PATCH 3/3] feat(rules): enter_project handshake (S4)

New enter_project(project_id) MCP tool composes get_project +
get_applicable_rules + get_project_milestone_summary + recent
open-tasks + recent notes into one round-trip, intended to be called
at session start (or whenever the active project changes) so Claude
has the full project context loaded before it starts mutating.

_INSTRUCTIONS now points Claude at enter_project for project-scoped
work, alongside the existing list_always_on_rules instruction. No
schema change; pure composition over existing services.

Closes the four-slice rules-consolidation plan (Scribe task #508):
S1+S2 (always_on flag + Scribe-first prompt, 658348f), S3 (project-
scoped rules, 43a860c), and now S4.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 src/fabledassistant/mcp/server.py         |  7 +++
 src/fabledassistant/mcp/tools/projects.py | 67 ++++++++++++++++++++
 tests/test_mcp_tool_projects.py           | 74 ++++++++++++++++++++++-
 3 files changed, 147 insertions(+), 1 deletion(-)

diff --git a/src/fabledassistant/mcp/server.py b/src/fabledassistant/mcp/server.py
index 3bac289..9b18199 100644
--- a/src/fabledassistant/mcp/server.py
+++ b/src/fabledassistant/mcp/server.py
@@ -56,6 +56,13 @@ creating a rule, call list_always_on_rules and list_rules(project_id=...) to
 avoid duplicates. Coordinate with the operator on whether a new rule belongs
 in a project, an existing rulebook+topic, or a new rulebook.
 
+When you are working on a specific project, call enter_project(project_id)
+ONCE at session start (or whenever the active project changes). It returns the
+project, its applicable_rules + project_rules + subscribed_rulebooks, milestone
+summary, open tasks, and recent notes — everything you need to know the lay of
+the land before mutating. Don't call get_project + get_applicable_rules + a
+search separately when enter_project already composes them.
+
 Plans are tasks with kind=plan, and Scribe is the canonical home for them.
 When you begin non-trivial work, call start_planning(project_id, title) FIRST —
 before any brainstorming, design, or plan-writing skill runs. start_planning
diff --git a/src/fabledassistant/mcp/tools/projects.py b/src/fabledassistant/mcp/tools/projects.py
index c17fc63..d31c47c 100644
--- a/src/fabledassistant/mcp/tools/projects.py
+++ b/src/fabledassistant/mcp/tools/projects.py
@@ -18,6 +18,7 @@ from __future__ import annotations
 
 from fabledassistant.mcp._context import current_user_id
 from fabledassistant.services import milestones as milestones_svc
+from fabledassistant.services import notes as notes_svc
 from fabledassistant.services import projects as projects_svc
 from fabledassistant.services import rulebooks as rulebooks_svc
 from fabledassistant.services import trash as trash_svc
@@ -34,6 +35,71 @@ async def list_projects() -> dict:
     return {"projects": [p.to_dict() for p in rows]}
 
 
+async def enter_project(project_id: int) -> dict:
+    """Session-start handshake: load full context for working on a project.
+
+    Call this FIRST whenever you're about to do project-scoped work
+    (start_planning, create_task, update_*, anything that takes a project_id).
+    One round-trip returns the project, its applicable rules (both rulebook-
+    subscribed and project-scoped), milestone progress, open tasks, and
+    recently-updated notes — everything you need to know the lay of the land
+    before mutating.
+
+    No persistent server state: this is a read snapshot. Re-call if the
+    session goes idle long enough that the data feels stale.
+
+    Args:
+        project_id: The project to enter.
+
+    Returns a dict with keys: project, milestone_summary, applicable_rules,
+    project_rules, subscribed_rulebooks, applicable_rules_truncated,
+    open_tasks, recent_notes.
+    """
+    uid = current_user_id()
+    project = await projects_svc.get_project(uid, project_id)
+    if project is None:
+        raise ValueError(f"project {project_id} not found")
+
+    applicable = await rulebooks_svc.get_applicable_rules(
+        project_id=project_id, user_id=uid,
+    )
+    milestone_summary = await milestones_svc.get_project_milestone_summary(
+        uid, project_id,
+    )
+    open_tasks, _ = await notes_svc.list_notes(
+        uid, is_task=True, project_id=project_id,
+        status=["todo", "in_progress"], sort="updated_at", limit=10,
+    )
+    recent_notes, _ = await notes_svc.list_notes(
+        uid, is_task=False, project_id=project_id,
+        sort="updated_at", limit=5,
+    )
+
+    return {
+        "project": project.to_dict(),
+        "milestone_summary": milestone_summary,
+        "applicable_rules": applicable["rules"],
+        "project_rules": applicable.get("project_rules", []),
+        "subscribed_rulebooks": applicable["subscribed_rulebooks"],
+        "applicable_rules_truncated": applicable["truncated"],
+        "open_tasks": [
+            {
+                "id": t.id, "title": t.title, "status": t.status,
+                "priority": t.priority, "task_kind": t.task_kind,
+                "milestone_id": t.milestone_id,
+            }
+            for t in open_tasks
+        ],
+        "recent_notes": [
+            {
+                "id": n.id, "title": n.title,
+                "updated_at": n.updated_at.isoformat() if n.updated_at else None,
+            }
+            for n in recent_notes
+        ],
+    }
+
+
 async def get_project(project_id: int) -> dict:
     """Fetch a Scribe project by ID.
 
@@ -137,6 +203,7 @@ async def delete_project(project_id: int) -> dict:
 def register(mcp) -> None:
     for fn in (
         list_projects,
+        enter_project,
         get_project,
         create_project,
         update_project,
diff --git a/tests/test_mcp_tool_projects.py b/tests/test_mcp_tool_projects.py
index 696eddb..cb84619 100644
--- a/tests/test_mcp_tool_projects.py
+++ b/tests/test_mcp_tool_projects.py
@@ -6,7 +6,7 @@ import pytest
 from fabledassistant.mcp._context import _user_id_ctx
 from fabledassistant.mcp.tools.projects import (
     list_projects, get_project, create_project,
-    update_project,
+    update_project, enter_project,
 )
 
 
@@ -130,3 +130,75 @@ async def test_update_project_raises_when_not_found():
     ):
         with pytest.raises(ValueError, match="project 999 not found"):
             await update_project(project_id=999, title="x")
+
+
+@pytest.mark.asyncio
+async def test_enter_project_composes_full_context():
+    """enter_project pulls project + rules + milestone summary + open tasks +
+    recent notes in one composed call."""
+    p = _fake_project(id=5, title="P")
+    applicable_payload = {
+        "rules": [{"id": 1, "title": "r1", "statement": "s",
+                   "topic_title": "t", "rulebook_title": "rb"}],
+        "project_rules": [{"id": 99, "title": "pr1", "statement": "ps"}],
+        "truncated": False,
+        "subscribed_rulebooks": [{"id": 2, "title": "rb"}],
+    }
+    milestone_summary = [{"id": 10, "title": "MS", "task_count": 3}]
+
+    task1 = MagicMock()
+    task1.id = 100; task1.title = "T1"; task1.status = "in_progress"
+    task1.priority = "high"; task1.task_kind = "work"; task1.milestone_id = 10
+    note1 = MagicMock()
+    note1.id = 200; note1.title = "N1"
+    note1.updated_at = None  # avoids datetime mocking
+
+    with patch(
+        "fabledassistant.mcp.tools.projects.projects_svc.get_project",
+        AsyncMock(return_value=p),
+    ), patch(
+        "fabledassistant.mcp.tools.projects.rulebooks_svc.get_applicable_rules",
+        AsyncMock(return_value=applicable_payload),
+    ), patch(
+        "fabledassistant.mcp.tools.projects.milestones_svc.get_project_milestone_summary",
+        AsyncMock(return_value=milestone_summary),
+    ), patch(
+        "fabledassistant.mcp.tools.projects.notes_svc.list_notes",
+        AsyncMock(side_effect=[([task1], 1), ([note1], 1)]),
+    ):
+        out = await enter_project(project_id=5)
+
+    assert out["project"]["id"] == 5
+    assert out["milestone_summary"] == milestone_summary
+    assert out["applicable_rules"][0]["title"] == "r1"
+    assert out["project_rules"][0]["id"] == 99
+    assert out["subscribed_rulebooks"] == [{"id": 2, "title": "rb"}]
+    assert out["open_tasks"][0]["id"] == 100
+    assert out["open_tasks"][0]["status"] == "in_progress"
+    assert out["recent_notes"][0]["id"] == 200
+
+
+@pytest.mark.asyncio
+async def test_enter_project_raises_when_project_not_found():
+    with patch(
+        "fabledassistant.mcp.tools.projects.projects_svc.get_project",
+        AsyncMock(return_value=None),
+    ):
+        with pytest.raises(ValueError, match="project 999 not found"):
+            await enter_project(project_id=999)
+
+
+def test_enter_project_registered_in_register():
+    """register(mcp) registers enter_project alongside the existing tools."""
+    from fabledassistant.mcp.tools.projects import register
+    registered: list[str] = []
+
+    class FakeMCP:
+        def tool(self, name=None):
+            def decorator(fn):
+                registered.append(name)
+                return fn
+            return decorator
+
+    register(FakeMCP())
+    assert "enter_project" in registered
-- 
2.52.0