@pharaoh-so/mcp 0.3.25 → 0.3.27

package/dist/lifecycle.d.ts

@@ -7,12 +7,22 @@
  */
 import { type Credentials } from "./credentials.js";
 import { type RefreshFailureAction } from "./refresh.js";
+/** Discriminated result from tryMidSessionRefresh. */
+export type MidSessionRefreshResult = {
+    ok: true;
+    creds: Credentials;
+} | {
+    ok: false;
+    action: RefreshFailureAction;
+    message: string;
+};
 /**
  * Attempt a silent refresh triggered by a mid-session TokenExpiredError.
- * Returns new credentials on success, null on any failure (messages already
- * printed). Caller decides whether to retry startProxy.
+ * Returns new credentials on success, or a tagged failure carrying the
+ * RefreshFailureAction so the caller can branch on the real classification
+ * instead of re-inferring from disk state.
  */
-export declare function tryMidSessionRefresh(creds: Credentials, server: string): Promise<Credentials | null>;
+export declare function tryMidSessionRefresh(creds: Credentials, server: string): Promise<MidSessionRefreshResult>;
 /**
  * Handle a failed `loadAndRefresh` at startup. Exits the process with the
  * appropriate message and creds-file state per the classified action.

package/dist/lifecycle.js

@@ -10,14 +10,15 @@ import { NPX_COMMAND, printLines } from "./helpers.js";
 import { refreshIfNeeded } from "./refresh.js";
 /**
  * Attempt a silent refresh triggered by a mid-session TokenExpiredError.
- * Returns new credentials on success, null on any failure (messages already
- * printed). Caller decides whether to retry startProxy.
+ * Returns new credentials on success, or a tagged failure carrying the
+ * RefreshFailureAction so the caller can branch on the real classification
+ * instead of re-inferring from disk state.
  */
 export async function tryMidSessionRefresh(creds, server) {
     const outcome = await refreshIfNeeded(creds, server);
     if (outcome.ok)
-        return outcome.creds;
-    // Log the failure reason before caller's exit path runs.
+        return { ok: true, creds: outcome.creds };
+    // Log the failure reason before the caller decides what to do.
     if (outcome.action === "reauth") {
         printLines("Pharaoh: refresh rejected — re-authentication required.", `  ${NPX_COMMAND}`, "");
         deleteCredentials();
@@ -27,7 +28,7 @@ export async function tryMidSessionRefresh(creds, server) {
         // the user knows their credentials file is intact (matches startup path).
         printLines(`Pharaoh: refresh failed (${outcome.action}) — ${outcome.message}`, "Credentials preserved; next startup will retry.", "");
     }
-    return null;
+    return { ok: false, action: outcome.action, message: outcome.message };
 }
 /**
  * Handle a failed `loadAndRefresh` at startup. Exits the process with the

package/dist/proxy-server.d.ts

@@ -8,11 +8,18 @@
  *
  * - startInAuthRequiredMode: cold start, no (or expired-refresh) credentials.
  *   Spins up a gateway, wraps it in AuthRequiredBackend, starts the server.
- *   Session C then polls hasValidCredentials() and calls setBackend() to swap
- *   to the SSE backend once the user finishes the device flow.
+ *   The caller supplies an `onAuthorized` callback that fires from inside the
+ *   backend the moment device flow completes — the callback swaps ProxyServer
+ *   over to an SseProxyBackend in place.
  *
  * - startInSseMode: happy path — valid credentials are already on disk. Starts
  *   the server directly with an SSE backend.
+ *
+ * Lifecycle:
+ * - `waitForLifetime()` is the single awaitable the main loop blocks on. It
+ *   resolves when Claude Code disconnects (stdio transport closed) and rejects
+ *   with typed errors when the active backend hits a terminal failure. Backend
+ *   swaps happen internally via callbacks; the main loop does NOT re-await.
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { type Backend } from "./backend.js";
@@ -27,6 +34,8 @@ export declare class ProxyServer {
     private transport;
     private backend;
     private started;
+    private transportClosed;
+    private transportClosedResolve;
     constructor(initialBackend: Backend);
     /**
      * Wire up list/call handlers. Each handler reads this.backend fresh at
@@ -45,6 +54,26 @@ export declare class ProxyServer {
      * Kept separate from start() so the stdio wiring stays implicit in prod.
      */
     startWithTransport(transport: StdioServerTransport): Promise<void>;
+    /**
+     * Block until either (a) the stdio transport closes cleanly (Claude Code
+     * disconnected) or (b) the current backend's supervisor promise rejects
+     * with a terminal error. Returns when the transport closes. Throws when
+     * a backend's waitForExit rejects.
+     *
+     * Swap-aware: if setBackend() is called while waitForLifetime is blocked,
+     * the old backend's exit promise is abandoned and the new backend's is
+     * awaited. This matters for "SSE → auth-required → SSE2" flows where we
+     * want errors from SSE2 to bubble up, not the already-dead SSE1.
+     */
+    waitForLifetime(): Promise<void>;
+    /**
+     * Used by setBackend to wake waitForLifetime so it can re-sample. Default
+     * no-op so a swap fired before waitForLifetime's first iteration (e.g. an
+     * onAuthorized that completes between proxy.start() and the first
+     * waitForLifetime call) doesn't crash. The missed wake is harmless — the
+     * next waitForLifetime iteration samples this.backend directly.
+     */
+    private backendSwappedSignal;
     /**
      * Swap the backend reference and fire a tools/list_changed notification so
      * the client re-fetches. No in-flight tracking — the SDK routes each call
@@ -59,12 +88,15 @@ export declare class ProxyServer {
  * the proxy in auth-required mode so the stdio connection stays alive while
  * the user completes the device flow.
  *
- * Returns the running ProxyServer and its gateway. Session C awaits
- * gateway.hasValidCredentials() on each tool call boundary, and once that
- * flips true, calls proxy.setBackend(createSseBackend(...)) to swap in the
- * real catalog.
+ * The caller supplies `opts.onAuthorized`, which fires from inside the
+ * AuthRequiredBackend the moment device flow completes. Typical implementation:
+ * swap the ProxyServer over to an SseProxyBackend so the next tool call goes
+ * to the real server. This keeps the proxy reference under the caller's
+ * control — the backend never imports ProxyServer.
  */
-export declare function startInAuthRequiredMode(server: string): Promise<{
+export declare function startInAuthRequiredMode(server: string, opts: {
+    onAuthorized: (creds: Credentials) => Promise<void>;
+}): Promise<{
     proxy: ProxyServer;
     gateway: DeviceFlowGateway;
 }>;

package/dist/proxy-server.js

@@ -8,11 +8,18 @@
  *
  * - startInAuthRequiredMode: cold start, no (or expired-refresh) credentials.
  *   Spins up a gateway, wraps it in AuthRequiredBackend, starts the server.
- *   Session C then polls hasValidCredentials() and calls setBackend() to swap
- *   to the SSE backend once the user finishes the device flow.
+ *   The caller supplies an `onAuthorized` callback that fires from inside the
+ *   backend the moment device flow completes — the callback swaps ProxyServer
+ *   over to an SseProxyBackend in place.
  *
  * - startInSseMode: happy path — valid credentials are already on disk. Starts
  *   the server directly with an SSE backend.
+ *
+ * Lifecycle:
+ * - `waitForLifetime()` is the single awaitable the main loop blocks on. It
+ *   resolves when Claude Code disconnects (stdio transport closed) and rejects
+ *   with typed errors when the active backend hits a terminal failure. Backend
+ *   swaps happen internally via callbacks; the main loop does NOT re-await.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -29,6 +36,8 @@ export class ProxyServer {
     transport = null;
     backend;
     started = false;
+    transportClosed;
+    transportClosedResolve;
     constructor(initialBackend) {
         this.backend = initialBackend;
         this.server = new Server({ name: "pharaoh-proxy", version: getPackageVersion() }, {
@@ -36,6 +45,9 @@ export class ProxyServer {
             // to throw; the SDK's assertNotificationCapability gates it.
             capabilities: { tools: { listChanged: true } },
         });
+        this.transportClosed = new Promise((resolve) => {
+            this.transportClosedResolve = resolve;
+        });
         this.registerHandlers();
     }
     /**
@@ -64,6 +76,11 @@ export class ProxyServer {
             await this.backend.start();
         this.transport = new StdioServerTransport();
         await this.server.connect(this.transport);
+        // Server.connect() wraps transport.onclose; use the Protocol-level hook
+        // instead so we don't clobber the SDK's chain. Fires when the transport
+        // closes cleanly (client disconnect) — not on error paths, which surface
+        // through backend.waitForExit() and the server's own onerror plumbing.
+        this.server.onclose = () => this.transportClosedResolve();
         this.started = true;
     }
     /**
@@ -78,8 +95,44 @@ export class ProxyServer {
         this.transport = transport;
         // biome-ignore lint/suspicious/noExplicitAny: test transport is a Transport, but the type import chain is awkward here
         await this.server.connect(transport);
+        this.server.onclose = () => this.transportClosedResolve();
         this.started = true;
     }
+    /**
+     * Block until either (a) the stdio transport closes cleanly (Claude Code
+     * disconnected) or (b) the current backend's supervisor promise rejects
+     * with a terminal error. Returns when the transport closes. Throws when
+     * a backend's waitForExit rejects.
+     *
+     * Swap-aware: if setBackend() is called while waitForLifetime is blocked,
+     * the old backend's exit promise is abandoned and the new backend's is
+     * awaited. This matters for "SSE → auth-required → SSE2" flows where we
+     * want errors from SSE2 to bubble up, not the already-dead SSE1.
+     */
+    async waitForLifetime() {
+        while (true) {
+            const swapSignal = new Promise((resolve) => {
+                this.backendSwappedSignal = () => resolve("swap");
+            });
+            const backendExit = this.backend.waitForExit?.() ?? new Promise(() => { });
+            const outcome = await Promise.race([
+                this.transportClosed.then(() => "closed"),
+                backendExit.then(() => "exit"),
+                swapSignal,
+            ]);
+            if (outcome === "swap")
+                continue; // re-sample waitForExit against the new backend
+            return; // "closed" or "exit" (the backend's waitForExit resolved cleanly)
+        }
+    }
+    /**
+     * Used by setBackend to wake waitForLifetime so it can re-sample. Default
+     * no-op so a swap fired before waitForLifetime's first iteration (e.g. an
+     * onAuthorized that completes between proxy.start() and the first
+     * waitForLifetime call) doesn't crash. The missed wake is harmless — the
+     * next waitForLifetime iteration samples this.backend directly.
+     */
+    backendSwappedSignal = () => { };
     /**
      * Swap the backend reference and fire a tools/list_changed notification so
      * the client re-fetches. No in-flight tracking — the SDK routes each call
@@ -99,15 +152,26 @@ export class ProxyServer {
         // Fire the notification after the swap so a client that races a list
         // request against it sees the new catalog.
         await this.server.sendToolListChanged();
-        // Fire-and-forget stop of the old backend. Errors here don't affect
-        // the running session — the swap has already happened.
+        // Wake any in-flight waitForLifetime so it re-samples the new backend's
+        // waitForExit. Without this, SSE2 errors after a swap-back would be lost.
+        this.backendSwappedSignal();
+        // Fire-and-forget stop of the old backend. The swap has already happened
+        // so stop failures can't break the running session — but log them so
+        // resource leaks (file descriptors, keepalive timers, EventSource auto-
+        // reconnect surviving a failed close) are visible.
         if (prev !== next && prev.stop) {
-            prev.stop().catch(() => { });
+            prev.stop().catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`Pharaoh: previous backend stop() failed — ${msg}\n`);
+            });
         }
     }
     async stop() {
         if (this.backend.stop) {
-            await this.backend.stop().catch(() => { });
+            await this.backend.stop().catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`Pharaoh: backend stop() failed during shutdown — ${msg}\n`);
+            });
         }
         if (this.transport) {
             await this.server.close().catch(() => { });
@@ -124,14 +188,28 @@ export class ProxyServer {
  * the proxy in auth-required mode so the stdio connection stays alive while
  * the user completes the device flow.
  *
- * Returns the running ProxyServer and its gateway. Session C awaits
- * gateway.hasValidCredentials() on each tool call boundary, and once that
- * flips true, calls proxy.setBackend(createSseBackend(...)) to swap in the
- * real catalog.
+ * The caller supplies `opts.onAuthorized`, which fires from inside the
+ * AuthRequiredBackend the moment device flow completes. Typical implementation:
+ * swap the ProxyServer over to an SseProxyBackend so the next tool call goes
+ * to the real server. This keeps the proxy reference under the caller's
+ * control — the backend never imports ProxyServer.
  */
-export async function startInAuthRequiredMode(server) {
+export async function startInAuthRequiredMode(server, opts) {
     const gateway = createGateway({ server });
-    const backend = new AuthRequiredBackend(gateway);
+    const backend = new AuthRequiredBackend(gateway, async () => {
+        // Pull fresh creds from the gateway (which just wrote them to disk) so
+        // the callback doesn't race a separate disk read. The gateway is the
+        // authoritative post-auth source.
+        const creds = gateway.getCredentials();
+        if (!creds) {
+            // Should never happen — gateway.handleToolCall() only returns null
+            // after persistAuthorizedToken sets lastCreds. Keep the guard so a
+            // future refactor doesn't silently ship a swap-to-nothing bug.
+            process.stderr.write("Pharaoh: authorized but no credentials available — skipping swap\n");
+            return;
+        }
+        await opts.onAuthorized(creds);
+    });
     const proxy = new ProxyServer(backend);
     await proxy.start();
     return { proxy, gateway };

package/dist/proxy.d.ts

@@ -1,16 +1,10 @@
 /**
- * Stdio ↔ SSE proxy entry point. Legacy export surface kept for the
- * in-flight handoff between Sessions B and C: index.ts (Session C's scope)
- * still imports `startProxy`, `TokenExpiredError`, and `TenantSuspendedError`
- * from here. Session C will rewrite index.ts to use ProxyServer/Backend
- * directly and `startProxy` will disappear at that point.
+ * Typed SSE errors + classifier. The stdio ↔ SSE wiring itself lives in
+ * backend.ts (SseProxyBackend); this module exports only the error types and
+ * the classifier so both the backend and tests can produce/assert on the
+ * same typed errors.
  *
- * Typed error classes and SSE classification live here because both the
- * legacy startProxy wrapper and the new SseProxyBackend (in backend.ts) need
- * to produce the same typed errors so downstream consumers don't care which
- * path surfaced them.
- *
- * RECONNECTION DESIGN (inherited by SseProxyBackend):
+ * RECONNECTION DESIGN (implemented in backend.ts SseProxyBackend):
  * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in
  * auto-reconnect (every 3s by default). This is problematic because:
  *   1. Each reconnect creates a NEW server-side session (new auth, new ID)
@@ -33,14 +27,13 @@ export declare class TenantSuspendedError extends Error {
  * Classify an SSE error — detect 401/403 and throw typed errors.
  * Exported for testability; used internally by the reconnect loop in
  * backend.ts.
- */
-export declare function classifySSEError(err: Error): void;
-/**
- * Legacy thin wrapper that starts the new ProxyServer in SSE mode and blocks
- * until the underlying SSE backend exits. Preserved so index.ts (Session C)
- * keeps compiling until the wiring PR; the return/throw contract matches the
- * original (resolves on clean exit, throws TokenExpiredError / TenantSuspendedError).
  *
- * @deprecated Session C will call ProxyServer / startInSseMode directly.
+ * The fallback uses status-prefix regex patterns rather than a bare
+ * `msg.includes("401")`. Session C calls this classifier on every reconnect
+ * error (not just SSE transport onerror events), so a substring match would
+ * misclassify any unrelated error text containing "401" — e.g. a port number,
+ * a timestamp suffix, or HTML body text echoed from a proxy. The regex
+ * requires an HTTP-shaped context so only actual status codes trigger a reauth
+ * loop.
  */
-export declare function startProxy(sseUrl: string, token: string): Promise<void>;
+export declare function classifySSEError(err: Error): void;

package/dist/proxy.js

@@ -1,16 +1,10 @@
 /**
- * Stdio ↔ SSE proxy entry point. Legacy export surface kept for the
- * in-flight handoff between Sessions B and C: index.ts (Session C's scope)
- * still imports `startProxy`, `TokenExpiredError`, and `TenantSuspendedError`
- * from here. Session C will rewrite index.ts to use ProxyServer/Backend
- * directly and `startProxy` will disappear at that point.
+ * Typed SSE errors + classifier. The stdio ↔ SSE wiring itself lives in
+ * backend.ts (SseProxyBackend); this module exports only the error types and
+ * the classifier so both the backend and tests can produce/assert on the
+ * same typed errors.
  *
- * Typed error classes and SSE classification live here because both the
- * legacy startProxy wrapper and the new SseProxyBackend (in backend.ts) need
- * to produce the same typed errors so downstream consumers don't care which
- * path surfaced them.
- *
- * RECONNECTION DESIGN (inherited by SseProxyBackend):
+ * RECONNECTION DESIGN (implemented in backend.ts SseProxyBackend):
  * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in
  * auto-reconnect (every 3s by default). This is problematic because:
  *   1. Each reconnect creates a NEW server-side session (new auth, new ID)
@@ -39,10 +33,19 @@ export class TenantSuspendedError extends Error {
  * Classify an SSE error — detect 401/403 and throw typed errors.
  * Exported for testability; used internally by the reconnect loop in
  * backend.ts.
+ *
+ * The fallback uses status-prefix regex patterns rather than a bare
+ * `msg.includes("401")`. Session C calls this classifier on every reconnect
+ * error (not just SSE transport onerror events), so a substring match would
+ * misclassify any unrelated error text containing "401" — e.g. a port number,
+ * a timestamp suffix, or HTML body text echoed from a proxy. The regex
+ * requires an HTTP-shaped context so only actual status codes trigger a reauth
+ * loop.
  */
 export function classifySSEError(err) {
     const msg = err.message ?? "";
-    // SseError from SDK includes the HTTP status code
+    // SseError from SDK includes the HTTP status code on `.code` — the
+    // authoritative signal.
     if ("code" in err) {
         const code = err.code;
         if (code === 401)
@@ -50,35 +53,15 @@ export function classifySSEError(err) {
         if (code === 403)
             throw new TenantSuspendedError(msg || "Tenant suspended");
     }
-    // Fallback: check message for status codes
-    if (msg.includes("401"))
-        throw new TokenExpiredError();
-    if (msg.includes("403"))
-        throw new TenantSuspendedError(msg || "Tenant suspended");
-}
-/**
- * Legacy thin wrapper that starts the new ProxyServer in SSE mode and blocks
- * until the underlying SSE backend exits. Preserved so index.ts (Session C)
- * keeps compiling until the wiring PR; the return/throw contract matches the
- * original (resolves on clean exit, throws TokenExpiredError / TenantSuspendedError).
- *
- * @deprecated Session C will call ProxyServer / startInSseMode directly.
- */
-export async function startProxy(sseUrl, token) {
-    // Lazy imports to keep module load order clean — backend.ts imports from
-    // proxy.ts for the typed errors and classifier above, so a top-level
-    // import would create a cycle.
-    const { createSseBackend } = await import("./backend.js");
-    const { ProxyServer } = await import("./proxy-server.js");
-    const backend = createSseBackend(sseUrl, token);
-    const proxy = new ProxyServer(backend);
-    await proxy.start();
-    // Block on the SSE reconnect loop — matches the original semantics of
-    // startProxy, which resolved only when the connection terminated.
-    try {
-        await backend.waitForExit();
-    }
-    finally {
-        await proxy.stop().catch(() => { });
+    // Fallback regex for errors that don't expose `.code`. Matches common HTTP
+    // status renderings: "HTTP 401", "HTTP/1.1 401", "401 Unauthorized",
+    // "status 401", "status: 401" — but NOT bare "401" anywhere in the string.
+    const m = msg.match(/\b(?:HTTP(?:\/[\d.]+)?|status:?)\s+(\d{3})\b|\b(\d{3})\s+(?:Unauthorized|Forbidden)\b/i);
+    if (m) {
+        const code = Number(m[1] ?? m[2]);
+        if (code === 401)
+            throw new TokenExpiredError();
+        if (code === 403)
+            throw new TenantSuspendedError(msg || "Tenant suspended");
     }
 }

package/inspect-tools.json

@@ -207,7 +207,7 @@
     },
     {
       "name": "get_design_system",
-      "description": "Discover the design system BEFORE creating any UI component.\n\nCALL THIS WHEN:\n• You're about to create a React/Vue/Svelte component — check what already exists\n• You need to know the canonical component for a UI pattern (button, input, modal)\n• You want to find design tokens (colors, spacing, typography) to use\n• You suspect raw HTML elements are used instead of existing components\n\nRETURNS: Components with props and usage count, design tokens with values, and anti-patterns where raw HTML is used instead of existing components. Screen/page components are excluded by default.\n\nEXAMPLES:\n• \"What components does this design system have?\"\n• \"Is there already a Button component I should use?\"\n• \"What color tokens are available?\"\n• \"Where are raw HTML elements used instead of components?\"\n\nWHY NOT JUST READ FILES: Design systems span dozens of files across multiple directories. This returns the complete inventory with usage frequency — the most-used components are the most canonical.",
+      "description": "Discover the design system BEFORE creating any UI component.\n\nCALL THIS WHEN:\n• You're about to create a React/Vue/Svelte component — check what already exists\n• You need to know the canonical component for a UI pattern (button, input, modal)\n• You want to find design tokens (colors, spacing, typography) to use\n• You suspect raw HTML elements are used instead of existing components\n\nRETURNS: Components with props and usage count (paginated), design tokens with values, and anti-patterns where raw HTML is used instead of existing components. Pass `path_pattern`, `name_prefix`, `offset`, or `limit` to narrow or page through results. Screen/page components are excluded by default.\n\nEXAMPLES:\n• \"What components does this design system have?\"\n• \"Is there already a Button component I should use?\"\n• \"What color tokens are available?\"\n• \"Show me all components in /atoms/\" → use path_pattern=\"/atoms/\"\n• \"Show me the next page\" → use offset=50\n\nWHY NOT JUST READ FILES: Design systems span dozens of files across multiple directories. This returns the complete inventory with usage frequency — the most-used components are the most canonical.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -231,6 +231,32 @@
             "default": false,
             "description": "Include screen/page components (*Screen, *Page, *View, *Route) that are typically app-level consumers, not reusable primitives",
             "type": "boolean"
+          },
+          "path_pattern": {
+            "description": "Substring match against File.path (e.g. '/atoms/', '/ui/Button'). Narrows to components whose file path contains this exact substring.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "name_prefix": {
+            "description": "Exact prefix match against component name (e.g. 'Button' matches Button, ButtonGroup, ButtonIcon). Case-sensitive.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "offset": {
+            "default": 0,
+            "description": "Pagination offset (0-based). Capped at 10000.",
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 10000
+          },
+          "limit": {
+            "default": 50,
+            "description": "Page size. Default 50, max 200.",
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 200
           }
         },
         "required": [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.25",
+  "version": "0.3.27",
   "description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
   "type": "module",
   "main": "dist/index.js",

package/skills/pharaoh/SKILL.md

@@ -27,14 +27,23 @@ For unmapped private repos, direct the user to install the Pharaoh GitHub App
 
 | Trigger | Call |
 |---------|------|
+| Before ANY architectural change | `get_vision_docs` — read the relevant MUST-bullets first |
 | Before modifying code | `get_module_context` + `get_blast_radius` |
 | Before writing new code | `search_functions` |
 | Before creating UI components | `get_design_system` |
 | Before tracing module connections | `query_dependencies` |
 | Before implementing a spec | `get_vision_docs` |
+| After a large refactor | `get_vision_gaps` — surface intent/implementation drift |
 | Before deleting code | `check_reachability` |
 | Initial orientation | `pharaoh_recon` (batches the above) |
 
+**Vision docs are first-class.** If the repo has a `docs/VISION.md`, it's
+the contract for what must always be true. Read it before touching
+architecture. If a change would violate a MUST-bullet, stop and raise it
+with the user before coding. If the repo has no VISION.md, offer to run
+`/pharaoh:vision` at the next natural break — it's the highest-leverage
+setup step for any team using Pharaoh.
+
 ## Anti-patterns
 
 - Do NOT read files one-by-one to understand architecture — call `get_codebase_map`.
@@ -45,10 +54,12 @@ For unmapped private repos, direct the user to install the Pharaoh GitHub App
 
 ## Automatic workflows
 
-**PR review:** `pharaoh_recon` (map + touched modules + blast radius) → `get_regression_risk` → `get_consolidation_opportunities`. Verdict: SHIP, SHIP WITH CHANGES, or BLOCK.
+**PR review:** `pharaoh_recon` (map + touched modules + blast radius) → `get_vision_docs` (relevant assertions) → `get_regression_risk` → `get_consolidation_opportunities`. Verdict: SHIP, SHIP WITH CHANGES, or BLOCK. Any PR touching code governed by a MUST-bullet should reference the assertion in the review.
 
 **Health audit:** `get_unused_code` → `get_test_coverage` → `get_regression_risk` → `get_vision_gaps` → `get_cross_repo_audit`. Grade A–F.
 
+**Vision maintenance:** When an architectural decision lands in a PR, update `docs/VISION.md` in the same commit — add an assertion if one is new, retire one if it no longer applies. Stale vision docs are worse than none.
+
 ## Using results
 
 - Lead with what the data reveals about this codebase — not a raw dump. Highlight surprises.

package/skills/plan/SKILL.md

@@ -45,11 +45,12 @@ Do NOT review from memory or assumptions. Query the actual codebase first.
 ### If Pharaoh MCP tools are available:
 
 1. `get_codebase_map` — current modules, hot files, dependency graph
-2. `search_functions` for keywords related to the plan — find existing code to reuse/extend
-3. `get_module_context` on affected modules — entry points, patterns, conventions
-4. `query_dependencies` between affected modules — coupling, circular deps
-5. `get_blast_radius` on the primary target of the change — know what breaks
-6. `check_reachability` on the primary target — verify it's actually reachable from entry points before worrying about it
+2. `get_vision_docs` — read the repo's architectural contract. If the plan touches a domain with a MUST-bullet, the assertion is a hard constraint on the plan. Raise it explicitly in Section 1. If `get_vision_docs` returns an empty-state scaffold, flag that the repo needs `/pharaoh:vision` before planning anything architectural.
+3. `search_functions` for keywords related to the plan — find existing code to reuse/extend
+4. `get_module_context` on affected modules — entry points, patterns, conventions
+5. `query_dependencies` between affected modules — coupling, circular deps
+6. `get_blast_radius` on the primary target of the change — know what breaks
+7. `check_reachability` on the primary target — verify it's actually reachable from entry points before worrying about it
 
 ### Without Pharaoh (graceful fallback):
 
@@ -77,10 +78,17 @@ Adapt depth to change size. Skip sections that don't apply. **After each section
 
 ### Section 1 — Architecture (skip for small/single-file changes)
 
+- **Vision alignment (check FIRST).** Does this plan touch a domain
+  governed by a MUST-bullet in `docs/VISION.md`? If yes, quote the
+  assertion and verify the plan doesn't violate it. If the plan would
+  violate a MUST, STOP and raise with the user — either the plan changes
+  or VISION.md needs an update first (with user approval).
 - Component boundaries and coupling concerns
 - Dependency graph: does this change shrink or expand surface area?
 - Data flow bottlenecks and single points of failure
 - Does this need new code at all, or can a human process / existing pattern solve it?
+- **If this plan introduces a new invariant**, call it out and include a
+  step in Section 6 to add a `### assertion` to VISION.md with a pairing TEST.
 
 ### Section 2 — Code Quality (always)
 

package/skills/review/SKILL.md

@@ -71,7 +71,8 @@ Then call these additional tools for data recon doesn't cover:
 - `get_regression_risk` — overall change risk score for the repo
 - `get_consolidation_opportunities` — duplicate logic the PR may introduce
 - `check_reachability` — are new exports wired to entry points?
-- `get_vision_gaps` — do changes align with or drift from specs?
+- `get_vision_docs` — read the repo's architectural contract. For every touched module, pull its relevant assertions. Any change touching code governed by a MUST-bullet must be checked against that assertion — if the change would violate the MUST, the verdict tips toward BLOCK unless VISION.md is updated in the same PR with user approval.
+- `get_vision_gaps` — do changes align with or drift from specs? New complex functions without a matching assertion are flagged; retired specs with implementing code are flagged.
 
 **Output of Phase 1:** Architecture map, module profiles for every touched module, blast radius for high-risk changes, dependency paths between coupled modules, regression risk level, duplication findings, reachability status, and spec alignment.
 
@@ -255,7 +256,8 @@ If none of these triggers are met, **skip Phase 3** and proceed to Phase 4.
 - Unreachable exports (new public code with zero callers)
 - New circular dependencies between modules
 - HIGH regression risk without corresponding test coverage
-- Vision spec violations (building against spec intent)
+- **A MUST-bullet in `docs/VISION.md` is violated by this change** (without VISION.md being updated in the same PR with user approval)
+- Vision spec drift: new complex function has no matching assertion AND the domain it lives in has existing assertions (implies invariants are expected here)
 - Any CRITICAL finding from Phase 2 or Phase 3 that is confirmed and unfixed
 - DISAGREE verdict from adversarial review on security-sensitive code, confirmed after verification
 - Unanchored Cypher query (MATCH without traversing through `Repo {name: $repo}`)