principles-disciple 1.76.0 → 1.77.0

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.76.0",
+  "version": "1.77.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.76.0",
+  "version": "1.77.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",

package/src/core/surface-guard.ts

@@ -0,0 +1,130 @@
+import {
+  PLUGIN_SURFACE_REGISTRY,
+  validateSurfaceRegistry,
+  getSurfacesByCategory,
+  type PluginSurfaceEntry,
+  type MvpCategory,
+} from '@principles/core/runtime-v2';
+import type { OpenClawPluginService } from '../openclaw-sdk.js';
+
+export interface SurfaceGuardResult {
+  passed: boolean;
+  enabledCoreSurfaces: string[];
+  disabledNonCoreSurfaces: string[];
+  violations: string[];
+  warnings: string[];
+}
+
+export function checkSurfaceGuard(): SurfaceGuardResult {
+  const validation = validateSurfaceRegistry(PLUGIN_SURFACE_REGISTRY);
+  const violations: string[] = [];
+  const warnings: string[] = [...validation.warnings];
+
+  const coreSurfaces = getSurfacesByCategory(PLUGIN_SURFACE_REGISTRY, 'core');
+  const enabledCore = coreSurfaces.filter(s => s.enabledByDefault);
+  const nonCoreEnabled = PLUGIN_SURFACE_REGISTRY.filter(
+    s => s.category !== 'core' && s.enabledByDefault,
+  );
+
+  if (nonCoreEnabled.length > 0) {
+    for (const surface of nonCoreEnabled) {
+      violations.push(
+        `non-core surface '${surface.id}' (${surface.category}) is enabledByDefault=true — must be false per ADR-0014`,
+      );
+    }
+  }
+
+  if (!validation.valid) {
+    violations.push(...validation.errors);
+  }
+
+  return {
+    passed: violations.length === 0,
+    enabledCoreSurfaces: enabledCore.map(s => s.id),
+    disabledNonCoreSurfaces: PLUGIN_SURFACE_REGISTRY
+      .filter(s => s.category !== 'core' && !s.enabledByDefault)
+      .map(s => s.id),
+    violations,
+    warnings,
+  };
+}
+
+export function getSurfaceIdForHook(hookEvent: string, label?: string): string {
+  if (label) {
+    return `hook:${hookEvent}.${label}`;
+  }
+  return `hook:${hookEvent}`;
+}
+
+export function getSurfaceIdForService(serviceName: string): string {
+  return `service:${serviceName}`;
+}
+
+export function isSurfaceEnabled(
+  surfaceId: string,
+  overrides: Record<string, boolean> = {},
+): { enabled: boolean; reason?: string } {
+  const entry = PLUGIN_SURFACE_REGISTRY.find(s => s.id === surfaceId);
+
+  if (!entry) {
+    return {
+      enabled: false,
+      reason: `surface '${surfaceId}' not found in registry — classify before enabling (PRI-289)`,
+    };
+  }
+
+  if (Object.hasOwn(overrides, surfaceId)) {
+    const override = overrides[surfaceId];
+    if (typeof override !== 'boolean') {
+      return { enabled: entry.enabledByDefault, reason: `override for '${surfaceId}' is not boolean, using default` };
+    }
+    if (entry.category === 'gone') {
+      return { enabled: false, reason: `surface '${surfaceId}' is gone and cannot be re-enabled` };
+    }
+    if (entry.category === 'core' && !override) {
+      return { enabled: true, reason: `surface '${surfaceId}' is core and cannot be disabled` };
+    }
+    return { enabled: override };
+  }
+
+  if (!entry.enabledByDefault && entry.disabledReason) {
+    return { enabled: false, reason: entry.disabledReason };
+  }
+
+  return { enabled: entry.enabledByDefault };
+}
+
+export type HookHandler<E, C, R> = (event: E, ctx: C) => R | Promise<R>;
+
+export function guardHook<E, C, R>(
+  surfaceId: string,
+  logger: { info?: (msg: string) => void; debug?: (msg: string) => void } | undefined,
+  handler: HookHandler<E, C, R>,
+): HookHandler<E, C, R> {
+  const check = isSurfaceEnabled(surfaceId);
+  if (check.enabled) {
+    return handler;
+  }
+  const reason = check.reason ?? 'surface not enabled';
+  return (_event: E, _ctx: C): R | Promise<R> => {
+    logger?.info?.(`[PD:surface-guard] SKIP ${surfaceId}: ${reason}`);
+    return undefined as R;
+  };
+}
+
+export function guardService<T extends OpenClawPluginService>(
+  surfaceId: string,
+  service: T,
+  logger?: { info?: (msg: string) => void; debug?: (msg: string) => void },
+): T | null {
+  const check = isSurfaceEnabled(surfaceId);
+  if (check.enabled) {
+    return service;
+  }
+  const reason = check.reason ?? 'surface not enabled';
+  logger?.info?.(`[PD:surface-guard] SKIP service ${surfaceId}: ${reason}`);
+  return null;
+}
+
+export { PLUGIN_SURFACE_REGISTRY, validateSurfaceRegistry, getSurfacesByCategory };
+export type { PluginSurfaceEntry, MvpCategory };

package/src/index.ts

@@ -62,6 +62,7 @@ import { computeRuntimeShadowTaskFingerprint, PD_LOCAL_PROFILES } from './utils/
 import type { WorkerProfile } from './core/model-deployment-registry.js';
 import { validateWorkspaceDir } from './core/workspace-dir-validation.js';
 import { resolveWorkspaceDirFromApi } from './core/path-resolver.js';
+import { checkSurfaceGuard, guardHook, guardService } from './core/surface-guard.js';
 
 // Track started workspaces — one-time init + evolution worker per workspace
 const startedWorkspaces = new Set<string>();
@@ -190,12 +191,25 @@ const plugin = {
     }, 1000);
     healthCheckTimer.unref(); // Don't keep process alive for health check
 
+    // ── MVP Surface Guard (PRI-289): Verify surface classification ──
+    const surfaceGuard = checkSurfaceGuard();
+    if (!surfaceGuard.passed) {
+      for (const violation of surfaceGuard.violations) {
+        api.logger.error(`[PD:surface-guard] VIOLATION: ${violation}`);
+      }
+    }
+    api.logger.info(`[PD:surface-guard] Core surfaces: ${surfaceGuard.enabledCoreSurfaces.join(', ')}`);
+    api.logger.info(`[PD:surface-guard] Disabled non-core surfaces: ${surfaceGuard.disabledNonCoreSurfaces.length}`);
+    for (const warning of surfaceGuard.warnings) {
+      api.logger.warn(`[PD:surface-guard] ${warning}`);
+    }
+
     const language = (api.pluginConfig?.language as string) || 'en';
 
     // ── Hook: Prompt Building ──
     api.on(
       'before_prompt_build',
-      async (event: PluginHookBeforePromptBuildEvent, ctx: PluginHookAgentContext): Promise<PluginHookBeforePromptBuildResult | void> => {
+      guardHook('hook:before_prompt_build', api.logger, async (event: PluginHookBeforePromptBuildEvent, ctx: PluginHookAgentContext): Promise<PluginHookBeforePromptBuildResult | void> => {
         const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_prompt_build');
         if (!workspaceDir) {
           api.logger.error(
@@ -251,13 +265,13 @@ const plugin = {
           });
           api.logger.error(`[PD] Error in before_prompt_build: ${String(err)}`);
         }
-      }
+      })
     );
 
     // ── Hook: Security Gate ──
     api.on(
       'before_tool_call',
-      (event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext): PluginHookBeforeToolCallResult | void => {
+      guardHook('hook:before_tool_call', api.logger, (event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext): PluginHookBeforeToolCallResult | void => {
         const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_tool_call');
         if (!workspaceDir) {
           api.logger.error(
@@ -286,13 +300,13 @@ const plugin = {
           }, { flushImmediately: true });
           api.logger.error(`[PD] Error in before_tool_call: ${String(err)}`);
         }
-      }
+      })
     );
 
     // ── Hook: Pain & Trust ──
     api.on(
       'after_tool_call',
-      (event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext): void => {
+      guardHook('hook:after_tool_call', api.logger, (event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext): void => {
         const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'after_tool_call');
         if (!workspaceDir) {
           api.logger.error(
@@ -319,13 +333,13 @@ const plugin = {
           }, { flushImmediately: true });
           api.logger.error(`[PD:EmpathyObserver] Error in after_tool_call: ${String(err)}`);
         }
-      }
+      })
     );
 
     // ── Hook: LLM Analysis ──
     api.on(
       'llm_output',
-      (event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext): void => {
+      guardHook('hook:llm_output', api.logger, (event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext): void => {
         const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'llm_output');
         if (!workspaceDir) {
           api.logger.error(
@@ -352,14 +366,14 @@ const plugin = {
           });
           api.logger.error(`[PD] Error in llm_output: ${String(err)}`);
         }
-      }
+      })
     );
 
     // ── Hook: Trajectory Collection (Behavior Evolution Phase 0) ──
     // Note: after_tool_call and llm_output are safe to collect
     api.on(
       'after_tool_call',
-      (event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext): void => {
+      guardHook('hook:after_tool_call.trajectory', api.logger, (event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext): void => {
         try {
           const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'trajectory.after_tool_call');
           if (!workspaceDir) return;
@@ -368,12 +382,12 @@ const plugin = {
         } catch (_err) {
           // Non-critical: don't log, just skip
         }
-      }
+      })
     );
 
     api.on(
       'llm_output',
-      (event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext): void => {
+      guardHook('hook:llm_output.trajectory', api.logger, (event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext): void => {
         try {
           const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'trajectory.llm_output');
           if (!workspaceDir) return;
@@ -382,14 +396,14 @@ const plugin = {
         } catch (_err) {
           // Non-critical: don't log, just skip
         }
-      }
+      })
     );
 
     // ── Hook: Subagent Loop Closure ──
     api.on(
       'subagent_spawning',
        
-      (event: PluginHookSubagentSpawningEvent, _ctx: PluginHookSubagentContext): void | PluginHookSubagentSpawningResult => {
+      guardHook('hook:subagent_spawning', api.logger, (event: PluginHookSubagentSpawningEvent, _ctx: PluginHookSubagentContext): void | PluginHookSubagentSpawningResult => {
         try {
           // FIX (B): Never fall back to '.' — fail-fast with ERROR log if workspaceDir cannot be resolved.
           // For subagent hooks, we use event.agentId as the target agent for workspace resolution.
@@ -428,12 +442,12 @@ const plugin = {
           api.logger.error(`[PD] Error in subagent_spawning shadow routing: ${String(err)}`);
           return { status: 'ok' }; // Don't block spawn on shadow observation errors
         }
-      }
+      })
     );
 
     api.on(
       'subagent_ended',
-      (event: PluginHookSubagentEndedEvent, ctx: PluginHookSubagentContext): void => {
+      guardHook('hook:subagent_ended', api.logger, (event: PluginHookSubagentEndedEvent, ctx: PluginHookSubagentContext): void => {
         try {
           // FIX (B): Never fall back to '.' — fail-fast with ERROR log if workspaceDir cannot be resolved.
           const workspaceDir = resolveWorkspaceDirFromApi(api, undefined);
@@ -465,11 +479,11 @@ const plugin = {
         } catch (err) {
           api.logger.error(`[PD] Error in subagent_ended: ${String(err)}`);
         }
-      }
+      })
     );
 
     // ── Hook: Lifecycle ──
-    api.on('before_reset', (event: PluginHookBeforeResetEvent, ctx: PluginHookAgentContext) => {
+    api.on('before_reset', guardHook('hook:before_reset', api.logger, (event: PluginHookBeforeResetEvent, ctx: PluginHookAgentContext) => {
       const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_reset');
       if (!workspaceDir) {
         api.logger.error(
@@ -480,9 +494,9 @@ const plugin = {
         return;
       }
       return handleBeforeReset(event, { ...ctx, workspaceDir });
-    });
+    }));
     
-    api.on('before_compaction', (event: PluginHookBeforeCompactionEvent, ctx: PluginHookAgentContext) => {
+    api.on('before_compaction', guardHook('hook:before_compaction', api.logger, (event: PluginHookBeforeCompactionEvent, ctx: PluginHookAgentContext) => {
       const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_compaction');
       if (!workspaceDir) {
         api.logger.error(
@@ -493,9 +507,9 @@ const plugin = {
         return;
       }
       return handleBeforeCompaction(event, { ...ctx, workspaceDir });
-    });
+    }));
     
-    api.on('after_compaction', (event: PluginHookAfterCompactionEvent, ctx: PluginHookAgentContext) => {
+    api.on('after_compaction', guardHook('hook:after_compaction', api.logger, (event: PluginHookAfterCompactionEvent, ctx: PluginHookAgentContext) => {
       const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'after_compaction');
       if (!workspaceDir) {
         api.logger.error(
@@ -506,17 +520,21 @@ const plugin = {
         return;
       }
       return handleAfterCompaction(event, { ...ctx, workspaceDir });
-    });
+    }));
 
     // ── Service: Background Evolution Worker ──
     try {
       EvolutionWorkerService.api = api;
-      api.registerService(EvolutionWorkerService);
-      api.registerService(TrajectoryService);
-      api.registerService(PDTaskService);
-      api.registerService(CentralSyncService);
+      const guardedEvolutionWorker = guardService('service:evolution-worker', EvolutionWorkerService, api.logger);
+      if (guardedEvolutionWorker) api.registerService(guardedEvolutionWorker);
+      const guardedTrajectory = guardService('service:trajectory', TrajectoryService, api.logger);
+      if (guardedTrajectory) api.registerService(guardedTrajectory);
+      const guardedPdTask = guardService('service:pd-task', PDTaskService, api.logger);
+      if (guardedPdTask) api.registerService(guardedPdTask);
+      const guardedCentralSync = guardService('service:central-sync', CentralSyncService, api.logger);
+      if (guardedCentralSync) api.registerService(guardedCentralSync);
     } catch (err) {
-      api.logger.error(`[PD] Failed to register EvolutionWorkerService: ${String(err)}`);
+      api.logger.error(`[PD] Failed to register services: ${String(err)}`);
     }
 
     // ── Slash Commands ──

package/tests/core-anti-growth.test.ts

@@ -123,6 +123,7 @@ describe('PRI-212 plugin core anti-growth guard', () => {
     'evolution-engine.ts',
     'runtime-v2-prompt-activation-reader.ts',
     'workspace-guidance-migrator.ts',
+    'surface-guard.ts',
   ] as const;
 
   // Category 6: Test files

package/tests/integration/mvp-surface-registry-guard.test.ts

@@ -0,0 +1,398 @@
+import { describe, expect, it } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  PLUGIN_SURFACE_REGISTRY,
+  validateSurfaceRegistry,
+  findUnclassifiedSurfaces,
+  getSurfacesByCategory,
+  getSurfacesByKind,
+} from '@principles/core/runtime-v2';
+
+function findRepoRoot(cwd: string): string {
+  let dir = cwd;
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.git'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return cwd;
+}
+
+const repoRoot = findRepoRoot(process.cwd());
+
+function read(relativePath: string): string {
+  return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8');
+}
+
+interface ApiOnRegistration {
+  event: string;
+  surfaceId: string | null;
+  rawLine: string;
+  index: number;
+}
+
+function extractApiOnRegistrations(source: string): ApiOnRegistration[] {
+  const registrations: ApiOnRegistration[] = [];
+  const apiOnPattern = /api\.on\s*\(\s*['"]([^'"]+)['"]\s*,\s*/g;
+  let match: RegExpExecArray | null;
+  let regIndex = 0;
+  while ((match = apiOnPattern.exec(source)) !== null) {
+    const event = match[1];
+    const afterMatch = source.slice(match.index + match[0].length);
+    const guardHookMatch = afterMatch.match(/^guardHook\s*\(\s*['"]([^'"]+)['"]\s*,/);
+    registrations.push({
+      event,
+      surfaceId: guardHookMatch ? guardHookMatch[1] : null,
+      rawLine: match[0],
+      index: regIndex++,
+    });
+  }
+  return registrations;
+}
+
+interface ServiceRegistration {
+  surfaceId: string;
+  index: number;
+}
+
+function extractServiceRegistrations(source: string): ServiceRegistration[] {
+  const registrations: ServiceRegistration[] = [];
+  const servicePattern = /guardService\s*\(\s*['"]([^'"]+)['"]\s*,/g;
+  let match: RegExpExecArray | null;
+  let serviceIndex = 0;
+  while ((match = servicePattern.exec(source)) !== null) {
+    registrations.push({
+      surfaceId: match[1],
+      index: serviceIndex++,
+    });
+  }
+  return registrations;
+}
+
+describe('MVP Surface Registry Guard (PRI-289)', () => {
+  describe('registry self-validation', () => {
+    it('PLUGIN_SURFACE_REGISTRY passes validateSurfaceRegistry', () => {
+      const result = validateSurfaceRegistry(PLUGIN_SURFACE_REGISTRY);
+      expect(result.valid).toBe(true);
+      expect(result.errors).toEqual([]);
+    });
+
+    it('has no duplicate surface ids', () => {
+      const ids = PLUGIN_SURFACE_REGISTRY.map(s => s.id);
+      const uniqueIds = new Set(ids);
+      expect(uniqueIds.size).toBe(ids.length);
+    });
+
+    it('core surfaces are all enabledByDefault', () => {
+      const coreSurfaces = getSurfacesByCategory(PLUGIN_SURFACE_REGISTRY, 'core');
+      for (const surface of coreSurfaces) {
+        expect(surface.enabledByDefault).toBe(true);
+      }
+    });
+
+    it('non-core surfaces are not enabledByDefault', () => {
+      const nonCore = PLUGIN_SURFACE_REGISTRY.filter(s => s.category !== 'core');
+      for (const surface of nonCore) {
+        expect(surface.enabledByDefault).toBe(false);
+      }
+    });
+
+    it('quiet/gone/legacy_retire surfaces have disabledReason', () => {
+      const disabled = PLUGIN_SURFACE_REGISTRY.filter(
+        s => s.category === 'quiet' || s.category === 'gone' || s.category === 'legacy_retire',
+      );
+      for (const surface of disabled) {
+        expect(surface.disabledReason).toBeDefined();
+        expect(typeof surface.disabledReason).toBe('string');
+        expect(surface.disabledReason!.length).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe('api.on() registration coverage — every hook must be guarded', () => {
+    const source = read('packages/openclaw-plugin/src/index.ts');
+    const registrations = extractApiOnRegistrations(source);
+
+    it('has at least one api.on registration', () => {
+      expect(registrations.length).toBeGreaterThan(0);
+    });
+
+    it('every api.on() handler is wrapped with guardHook()', () => {
+      const unguarded = registrations.filter(r => r.surfaceId === null);
+      if (unguarded.length > 0) {
+        const details = unguarded.map(r => `api.on('${r.event}', ...) #${r.index} — NOT wrapped with guardHook`);
+        throw new Error(
+          `Found ${unguarded.length} unguarded api.on() registration(s):\n${details.join('\n')}\n` +
+          `Every api.on() handler MUST be wrapped with guardHook('<surfaceId>', api.logger, ...) per PRI-289.`,
+        );
+      }
+    });
+
+    it('every guardHook surface id exists in PLUGIN_SURFACE_REGISTRY', () => {
+      const guarded = registrations.filter(r => r.surfaceId !== null);
+      const registeredIds = new Set(PLUGIN_SURFACE_REGISTRY.map(s => s.id));
+      const unclassified: string[] = [];
+      for (const reg of guarded) {
+        if (!registeredIds.has(reg.surfaceId!)) {
+          unclassified.push(reg.surfaceId!);
+        }
+      }
+      expect(unclassified).toEqual([]);
+    });
+
+    it('each individual api.on registration is covered (no dedup by event name)', () => {
+      const guarded = registrations.filter(r => r.surfaceId !== null);
+      const registeredIds = new Set(PLUGIN_SURFACE_REGISTRY.map(s => s.id));
+      for (const reg of guarded) {
+        expect(registeredIds.has(reg.surfaceId!)).toBe(true);
+      }
+    });
+
+    it('after_tool_call has two registrations: core + trajectory', () => {
+      const afterToolCallRegs = registrations.filter(r => r.event === 'after_tool_call');
+      expect(afterToolCallRegs.length).toBe(2);
+      expect(afterToolCallRegs[0].surfaceId).toBe('hook:after_tool_call');
+      expect(afterToolCallRegs[1].surfaceId).toBe('hook:after_tool_call.trajectory');
+    });
+
+    it('llm_output has two registrations: core + trajectory', () => {
+      const llmOutputRegs = registrations.filter(r => r.event === 'llm_output');
+      expect(llmOutputRegs.length).toBe(2);
+      expect(llmOutputRegs[0].surfaceId).toBe('hook:llm_output');
+      expect(llmOutputRegs[1].surfaceId).toBe('hook:llm_output.trajectory');
+    });
+
+    it('total api.on registrations with guardHook match registry hook count', () => {
+      const guarded = registrations.filter(r => r.surfaceId !== null);
+      const registryHookCount = PLUGIN_SURFACE_REGISTRY.filter(s => s.kind === 'hook').length;
+      expect(guarded.length).toBe(registryHookCount);
+    });
+
+    it('all guardHook calls pass api.logger as second argument', () => {
+      const guardHookWithLogger = /guardHook\s*\(\s*['"][^'"]+['"]\s*,\s*api\.logger\s*,/g;
+      const guardHookTotal = /guardHook\s*\(\s*['"][^'"]+['"]\s*,/g;
+      const withLoggerCount = (source.match(guardHookWithLogger) ?? []).length;
+      const totalCount = (source.match(guardHookTotal) ?? []).length;
+      expect(withLoggerCount).toBe(totalCount);
+    });
+  });
+
+  describe('service registration coverage — per-registration', () => {
+    it('every guardService() call in index.ts has a classified surface id', () => {
+      const source = read('packages/openclaw-plugin/src/index.ts');
+      const registrations = extractServiceRegistrations(source);
+
+      expect(registrations.length).toBeGreaterThan(0);
+
+      const registeredIds = new Set(
+        PLUGIN_SURFACE_REGISTRY.filter(s => s.kind === 'service').map(s => s.id),
+      );
+
+      const unclassified: string[] = [];
+      for (const reg of registrations) {
+        if (!registeredIds.has(reg.surfaceId)) {
+          unclassified.push(reg.surfaceId);
+        }
+      }
+
+      expect(unclassified).toEqual([]);
+    });
+
+    it('total service registrations match expected count', () => {
+      const source = read('packages/openclaw-plugin/src/index.ts');
+      const registrations = extractServiceRegistrations(source);
+
+      const registryServiceCount = PLUGIN_SURFACE_REGISTRY.filter(s => s.kind === 'service').length;
+      expect(registrations.length).toBe(registryServiceCount);
+    });
+  });
+
+  describe('ADR-0014 compliance', () => {
+    it('only MVP-Core surfaces are enabledByDefault', () => {
+      const enabledByDefault = PLUGIN_SURFACE_REGISTRY.filter(s => s.enabledByDefault);
+      for (const surface of enabledByDefault) {
+        expect(surface.category).toBe('core');
+      }
+    });
+
+    it('core hooks match ADR-0014 MVP-Core activation paths', () => {
+      const coreHooks = getSurfacesByKind(PLUGIN_SURFACE_REGISTRY, 'hook')
+        .filter(s => s.category === 'core')
+        .map(s => s.id);
+
+      expect(coreHooks).toContain('hook:before_prompt_build');
+      expect(coreHooks).toContain('hook:before_tool_call');
+      expect(coreHooks).toContain('hook:after_tool_call');
+      expect(coreHooks).toContain('hook:llm_output');
+    });
+
+    it('evolution-worker service is MVP-Quiet (PRI-288/ADR-0014 alignment)', () => {
+      const ew = PLUGIN_SURFACE_REGISTRY.find(s => s.id === 'service:evolution-worker');
+      expect(ew).toBeDefined();
+      expect(ew!.category).toBe('quiet');
+      expect(ew!.enabledByDefault).toBe(false);
+      expect(ew!.disabledReason).toContain('PRI-288');
+    });
+
+    it('evolution-worker startup is MVP-Quiet (PRI-288/ADR-0014 alignment)', () => {
+      const ew = PLUGIN_SURFACE_REGISTRY.find(s => s.id === 'startup:evolution-worker');
+      expect(ew).toBeDefined();
+      expect(ew!.category).toBe('quiet');
+      expect(ew!.enabledByDefault).toBe(false);
+      expect(ew!.disabledReason).toContain('PRI-288');
+    });
+
+    it('trajectory hooks are MVP-Quiet (ADR-0014 §2.5)', () => {
+      const trajectoryHooks = PLUGIN_SURFACE_REGISTRY.filter(
+        s => s.kind === 'hook' && s.id.includes('trajectory'),
+      );
+      for (const hook of trajectoryHooks) {
+        expect(hook.category).toBe('quiet');
+        expect(hook.enabledByDefault).toBe(false);
+      }
+    });
+
+    it('subagent/shadow hooks are MVP-Quiet (ADR-0014 §2.5)', () => {
+      const shadowHooks = PLUGIN_SURFACE_REGISTRY.filter(
+        s => s.kind === 'hook' && (s.id.includes('subagent') || s.id.includes('shadow')),
+      );
+      for (const hook of shadowHooks) {
+        expect(hook.category).toBe('quiet');
+        expect(hook.enabledByDefault).toBe(false);
+      }
+    });
+
+    it('lifecycle hooks are MVP-Quiet (ADR-0014 §2.5)', () => {
+      const lifecycleHooks = PLUGIN_SURFACE_REGISTRY.filter(
+        s => s.kind === 'hook' && (s.id.includes('reset') || s.id.includes('compaction')),
+      );
+      for (const hook of lifecycleHooks) {
+        expect(hook.category).toBe('quiet');
+        expect(hook.enabledByDefault).toBe(false);
+      }
+    });
+
+    it('central-sync service is MVP-Quiet (ADR-0014 §2.5: single workspace)', () => {
+      const centralSync = PLUGIN_SURFACE_REGISTRY.find(s => s.id === 'service:central-sync');
+      expect(centralSync).toBeDefined();
+      expect(centralSync!.category).toBe('quiet');
+      expect(centralSync!.enabledByDefault).toBe(false);
+    });
+  });
+
+  describe('surface guard runtime', () => {
+    it('checkSurfaceGuard passes with current registry', async () => {
+      const { checkSurfaceGuard } = await import('../../src/core/surface-guard.js');
+      const result = checkSurfaceGuard();
+      expect(result.passed).toBe(true);
+      expect(result.violations).toEqual([]);
+    });
+
+    it('isSurfaceEnabled returns false for unknown surface with reason', async () => {
+      const { isSurfaceEnabled } = await import('../../src/core/surface-guard.js');
+      const result = isSurfaceEnabled('hook:unknown_new_hook');
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toContain('not found in registry');
+    });
+
+    it('isSurfaceEnabled returns true for core surfaces', async () => {
+      const { isSurfaceEnabled } = await import('../../src/core/surface-guard.js');
+      const result = isSurfaceEnabled('hook:before_prompt_build');
+      expect(result.enabled).toBe(true);
+    });
+
+    it('isSurfaceEnabled returns false for unknown surfaces even with override', async () => {
+      const { isSurfaceEnabled } = await import('../../src/core/surface-guard.js');
+      const result = isSurfaceEnabled('hook:nonexistent_gone', { 'hook:nonexistent_gone': true });
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toContain('not found in registry');
+    });
+
+    it('isSurfaceEnabled returns true for core surfaces even with false override', async () => {
+      const { isSurfaceEnabled } = await import('../../src/core/surface-guard.js');
+      const result = isSurfaceEnabled('hook:before_prompt_build', { 'hook:before_prompt_build': false });
+      expect(result.enabled).toBe(true);
+      expect(result.reason).toContain('core');
+    });
+
+    it('isSurfaceEnabled returns false for quiet surfaces by default', async () => {
+      const { isSurfaceEnabled } = await import('../../src/core/surface-guard.js');
+      const result = isSurfaceEnabled('hook:after_tool_call.trajectory');
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toBeDefined();
+    });
+
+    it('isSurfaceEnabled allows quiet surfaces with explicit override', async () => {
+      const { isSurfaceEnabled } = await import('../../src/core/surface-guard.js');
+      const result = isSurfaceEnabled('hook:after_tool_call.trajectory', { 'hook:after_tool_call.trajectory': true });
+      expect(result.enabled).toBe(true);
+    });
+
+    it('guardHook returns original handler for core surfaces', async () => {
+      const { guardHook } = await import('../../src/core/surface-guard.js');
+      const handler = () => 'result';
+      const guarded = guardHook('hook:before_prompt_build', undefined, handler);
+      expect(guarded).toBe(handler);
+    });
+
+    it('guardHook returns no-op handler for quiet surfaces', async () => {
+      const { guardHook } = await import('../../src/core/surface-guard.js');
+      const handler = () => 'result';
+      const guarded = guardHook('hook:after_tool_call.trajectory', undefined, handler);
+      expect(guarded).not.toBe(handler);
+      expect(guarded({} as never, {} as never)).toBeUndefined();
+    });
+
+    it('guardHook returns no-op handler for unregistered surfaces', async () => {
+      const { guardHook } = await import('../../src/core/surface-guard.js');
+      const handler = () => 'result';
+      const guarded = guardHook('hook:nonexistent_hook', undefined, handler);
+      expect(guarded).not.toBe(handler);
+    });
+
+    it('guardHook logs disabled reason via logger for quiet surfaces', async () => {
+      const { guardHook } = await import('../../src/core/surface-guard.js');
+      const logs: string[] = [];
+      const logger = { info: (msg: string) => { logs.push(msg); } };
+      const handler = () => 'result';
+      const guarded = guardHook('hook:after_tool_call.trajectory', logger, handler);
+      guarded({} as never, {} as never);
+      expect(logs.length).toBe(1);
+      expect(logs[0]).toContain('[PD:surface-guard] SKIP');
+      expect(logs[0]).toContain('hook:after_tool_call.trajectory');
+    });
+
+    it('guardHook does not log for enabled surfaces', async () => {
+      const { guardHook } = await import('../../src/core/surface-guard.js');
+      const logs: string[] = [];
+      const logger = { info: (msg: string) => { logs.push(msg); } };
+      const handler = () => 'result';
+      const guarded = guardHook('hook:before_prompt_build', logger, handler);
+      guarded({} as never, {} as never);
+      expect(logs.length).toBe(0);
+    });
+
+    it('guardService returns null for evolution-worker (quiet, default off)', async () => {
+      const { guardService } = await import('../../src/core/surface-guard.js');
+      const service = { api: null, start: () => {} };
+      const guarded = guardService('service:evolution-worker', service);
+      expect(guarded).toBeNull();
+    });
+
+    it('guardService returns null for quiet surfaces', async () => {
+      const { guardService } = await import('../../src/core/surface-guard.js');
+      const service = { api: null, start: () => {} };
+      const guarded = guardService('service:trajectory', service);
+      expect(guarded).toBeNull();
+    });
+
+    it('guardService returns null for unregistered surfaces', async () => {
+      const { guardService } = await import('../../src/core/surface-guard.js');
+      const service = { api: null, start: () => {} };
+      const guarded = guardService('service:nonexistent_service', service);
+      expect(guarded).toBeNull();
+    });
+  });
+});