refactor(prism-facet): become a pure registration framework

Strip all Hangman-Lab-specific content out of PrismFacet so it can be
reused by any project. Content (always router, pcexec-convention prompt,
fabric-chat-injector hook) moves to the new sibling plugin ClawPrompts.

Mechanism additions:
- `globalThis.__prismFacet` cross-plugin API installed at module-import
  time (so consumers loaded before PrismFacet can still register):
    .addRouter(name, resolveFn)
    .addRule(router, key, { file })
- core/rule-store: tier rules into `persistent` (rules.json, mutated by
  the prompt-rules admin tool) and `external` (in-memory, registered by
  other plugins via the API). Persistent overrides external on conflict.
- core/router-loader: addExternalRouter() for programmatic registration
  into the same map the file-based loader uses.
- index.ts: drops registerFabricChatInjector wiring, registerBeforePromptBuild
  remains.

Removed (now shipped from ClawPrompts):
- plugin/routers/always.ts
- plugin/hooks/fabric-chat-injector.ts
- plugin/prompts/pcexec-convention.md
- plugin/rules.json: now `{}`; ClawPrompts registers its rule externally

What still lives in PrismFacet:
- before_prompt_build hook (the wiring between routers/rules and the
  agent's system prompt)
- prompt-rules admin tool (lists + mutates persistent rules)
- file-based routersDir / rulesFile scanning (kept for operator ad-hoc
  use; ClawPrompts uses the API instead)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

plugin/core/cross-plugin-api.ts

@@ -0,0 +1,83 @@
+/**
+ * Cross-plugin API: globalThis.__prismFacet
+ *
+ * PrismFacet is the registration mechanism (routers, rules, the
+ * before_prompt_build hook that resolves them); other plugins (notably
+ * ClawPrompts) supply the actual content by calling into this API at
+ * their own register() time.
+ *
+ * Installation idempotence: safe to call install() multiple times — the
+ * function attaches the same set of methods to globalThis.__prismFacet
+ * if not already present. Plugin reload doesn't break consumers.
+ *
+ * If a consumer plugin (ClawPrompts) loads BEFORE PrismFacet, the
+ * `globalThis.__prismFacet` slot will be undefined at the consumer's
+ * register() time. To make load-order independence work, this module
+ * pre-creates the slot at module-import time too — consumers can call
+ * .addRouter / .addRule even if PrismFacet's register() hasn't run yet
+ * (the registration still lands in the shared maps).
+ */
+import { addExternalRouter, type RouterContext } from "./router-loader.js";
+import { addExternalRule } from "./rule-store.js";
+
+const _G = globalThis as Record<string, unknown>;
+
+export interface PrismFacetCrossPluginApi {
+  /**
+   * Register a router programmatically.
+   * @param name router name (matches the "router:" prefix of rule keys)
+   * @param resolve function returning a key string for the given context
+   *                (or empty/null to skip this router for this context)
+   */
+  addRouter(
+    name: string,
+    resolve: (ctx: RouterContext) => string | Promise<string>,
+  ): void;
+
+  /**
+   * Register a rule programmatically (in-memory; persistent rules.json
+   * entries set by the prompt-rules tool take precedence on conflict).
+   * @param routerName router this rule binds to
+   * @param key value the router must resolve to for this rule to fire
+   * @param prompt either { file: "/abs/path.md" } or { text: "..." }
+   */
+  addRule(
+    routerName: string,
+    key: string,
+    prompt: { file?: string; text?: string },
+  ): void;
+}
+
+/** Idempotent install. Called from PrismFacet's register(). Also runs
+ * at module-import time below so that consumer plugins loading before
+ * PrismFacet still find a usable API. */
+export function installCrossPluginApi(): PrismFacetCrossPluginApi {
+  const existing = _G["__prismFacet"] as PrismFacetCrossPluginApi | undefined;
+  if (existing && typeof existing.addRouter === "function") return existing;
+
+  const api: PrismFacetCrossPluginApi = {
+    addRouter(name, resolve) {
+      addExternalRouter(name, resolve);
+    },
+    addRule(routerName, key, prompt) {
+      // Phase 1: only file-based prompts are wired through the existing
+      // injector. `text` inline prompts will need a tmpfile-or-store
+      // backend; surfaced as a TODO so an early caller failing loudly
+      // beats silently dropping the prompt.
+      if (!prompt.file) {
+        throw new Error(
+          "__prismFacet.addRule: only { file: '/abs/path.md' } is supported today; " +
+          "inline { text } pending injector update",
+        );
+      }
+      addExternalRule(routerName, key, prompt.file);
+    },
+  };
+  _G["__prismFacet"] = api;
+  return api;
+}
+
+// Eager install on module load so a consumer plugin importing into the
+// same gateway process can register even if it runs before PrismFacet's
+// register() does.
+installCrossPluginApi();

plugin/core/router-loader.ts

@@ -75,3 +75,21 @@ export function getRouters(): LoadedRouter[] {
 export function getRouterNames(): string[] {
   return Array.from(getRouterMap().keys());
 }
+
+/**
+ * Cross-plugin API: register a router programmatically. Other plugins
+ * (e.g. ClawPrompts) call this via globalThis.__prismFacet.addRouter
+ * to publish a router without dropping a .ts file in PrismFacet's
+ * routersDir. Replaces any existing router of the same name.
+ */
+export function addExternalRouter(
+  name: string,
+  resolveFn: (ctx: RouterContext) => string | Promise<string>,
+): void {
+  const map = getRouterMap();
+  map.set(name, {
+    name,
+    filePath: `<external: registered via __prismFacet.addRouter>`,
+    module: { resolve: resolveFn },
+  });
+}

plugin/core/rule-store.ts

@@ -1,16 +1,34 @@
+/**
+ * Two-tier rule store: persistent (operator/admin rules loaded from
+ * rules.json, mutated by the prompt-rules tool) and external (in-memory
+ * rules registered by other plugins via the __prismFacet cross-plugin
+ * API). External rules are NOT saved to disk — they belong to the
+ * registering plugin and are re-registered on every gateway start.
+ *
+ * Lookup precedence: persistent > external (operator wins over plugin
+ * defaults so an explicit rules.json override is honored).
+ */
 import { readFileSync, writeFileSync } from "node:fs";
 
 export type RuleStore = Record<string, string>; // "router:key" → prompt file path
 
 const _G = globalThis as Record<string, unknown>;
-const RULES_KEY = "_prismFacetRules";
+const PERSISTENT_KEY = "_prismFacetRules";
+const EXTERNAL_KEY = "_prismFacetExternalRules";
 const RULES_PATH_KEY = "_prismFacetRulesPath";
 
-function getRules(): RuleStore {
-  if (!_G[RULES_KEY] || typeof _G[RULES_KEY] !== "object") {
-    _G[RULES_KEY] = {};
+function getPersistent(): RuleStore {
+  if (!_G[PERSISTENT_KEY] || typeof _G[PERSISTENT_KEY] !== "object") {
+    _G[PERSISTENT_KEY] = {};
   }
-  return _G[RULES_KEY] as RuleStore;
+  return _G[PERSISTENT_KEY] as RuleStore;
+}
+
+function getExternal(): RuleStore {
+  if (!_G[EXTERNAL_KEY] || typeof _G[EXTERNAL_KEY] !== "object") {
+    _G[EXTERNAL_KEY] = {};
+  }
+  return _G[EXTERNAL_KEY] as RuleStore;
 }
 
 function getRulesPath(): string {
@@ -20,26 +38,32 @@ function getRulesPath(): string {
 function save(): void {
   const p = getRulesPath();
   if (!p) return;
-  writeFileSync(p, JSON.stringify(getRules(), null, 2) + "\n", "utf8");
+  writeFileSync(p, JSON.stringify(getPersistent(), null, 2) + "\n", "utf8");
 }
 
 export function initRuleStore(filePath: string): void {
   _G[RULES_PATH_KEY] = filePath;
   try {
     const raw = readFileSync(filePath, "utf8");
-    _G[RULES_KEY] = JSON.parse(raw) as RuleStore;
+    _G[PERSISTENT_KEY] = JSON.parse(raw) as RuleStore;
   } catch {
-    _G[RULES_KEY] = {};
+    _G[PERSISTENT_KEY] = {};
   }
 }
 
+/** Operator-facing addRule (writes through to rules.json on disk). */
 export function addRule(router: string, key: string, promptFile: string): void {
-  getRules()[`${router}:${key}`] = promptFile;
+  getPersistent()[`${router}:${key}`] = promptFile;
   save();
 }
 
+/** Cross-plugin API: register a rule that lives in memory only. */
+export function addExternalRule(router: string, key: string, promptFile: string): void {
+  getExternal()[`${router}:${key}`] = promptFile;
+}
+
 export function removeRule(router: string, key: string): boolean {
-  const rules = getRules();
+  const rules = getPersistent();
   const ruleKey = `${router}:${key}`;
   if (!(ruleKey in rules)) return false;
   delete rules[ruleKey];
@@ -47,10 +71,22 @@ export function removeRule(router: string, key: string): boolean {
   return true;
 }
 
+/** Lookup. Persistent (rules.json) overrides external (plugin defaults). */
 export function getRule(router: string, key: string): string | undefined {
-  return getRules()[`${router}:${key}`];
+  const persistentValue = getPersistent()[`${router}:${key}`];
+  if (persistentValue) return persistentValue;
+  return getExternal()[`${router}:${key}`];
 }
 
+/** Merged view for the admin tool. Persistent overrides external. */
 export function listRules(): Record<string, string> {
-  return { ...getRules() };
+  return { ...getExternal(), ...getPersistent() };
+}
+
+/** Admin tool needs to know which tier a rule came from. */
+export function listRulesTiered(): {
+  persistent: RuleStore;
+  external: RuleStore;
+} {
+  return { persistent: { ...getPersistent() }, external: { ...getExternal() } };
 }