principles-disciple 1.79.0 → 1.80.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.79.0",
+  "version": "1.80.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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

package/tests/core/surface-guard.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  checkSurfaceGuard,
+  isSurfaceEnabled,
+  guardHook,
+  guardService,
+  getSurfaceIdForHook,
+  getSurfaceIdForService,
+} from '../../src/core/surface-guard.js';
+import { PLUGIN_SURFACE_REGISTRY } from '@principles/core/runtime-v2';
+import type { OpenClawPluginService } from '../../src/openclaw-sdk.js';
+
+describe('surface-guard', () => {
+  describe('getSurfaceIdForHook', () => {
+    it('generates correct surface id without label', () => {
+      expect(getSurfaceIdForHook('before_tool_call')).toBe('hook:before_tool_call');
+    });
+
+    it('generates correct surface id with label', () => {
+      expect(getSurfaceIdForHook('after_tool_call', 'trajectory')).toBe('hook:after_tool_call.trajectory');
+    });
+  });
+
+  describe('getSurfaceIdForService', () => {
+    it('generates correct surface id for service', () => {
+      expect(getSurfaceIdForService('evolution-worker')).toBe('service:evolution-worker');
+    });
+  });
+
+  describe('checkSurfaceGuard', () => {
+    it('returns passed=true when registry is valid', () => {
+      const result = checkSurfaceGuard();
+      expect(result.passed).toBe(true);
+      expect(result.violations).toEqual([]);
+    });
+
+    it('includes enabled core surfaces', () => {
+      const result = checkSurfaceGuard();
+      expect(result.enabledCoreSurfaces.length).toBeGreaterThan(0);
+      for (const surfaceId of result.enabledCoreSurfaces) {
+        const entry = PLUGIN_SURFACE_REGISTRY.find(s => s.id === surfaceId);
+        expect(entry).toBeDefined();
+        expect(entry?.category).toBe('core');
+      }
+    });
+
+    it('includes disabled non-core surfaces', () => {
+      const result = checkSurfaceGuard();
+      expect(result.disabledNonCoreSurfaces.length).toBeGreaterThan(0);
+      for (const surfaceId of result.disabledNonCoreSurfaces) {
+        const entry = PLUGIN_SURFACE_REGISTRY.find(s => s.id === surfaceId);
+        expect(entry).toBeDefined();
+        expect(entry?.category).not.toBe('core');
+        expect(entry?.enabledByDefault).toBe(false);
+      }
+    });
+
+    it('returns violations when non-core surface is enabledByDefault', () => {
+      const result = checkSurfaceGuard();
+      const nonCoreEnabled = PLUGIN_SURFACE_REGISTRY.filter(
+        s => s.category !== 'core' && s.enabledByDefault,
+      );
+      if (nonCoreEnabled.length > 0) {
+        expect(result.violations.length).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe('isSurfaceEnabled', () => {
+    it('returns enabled=true for core surface without override', () => {
+      const result = isSurfaceEnabled('hook:before_prompt_build');
+      expect(result.enabled).toBe(true);
+      expect(result.reason).toBeUndefined();
+    });
+
+    it('returns enabled=false for quiet surface without override', () => {
+      const result = isSurfaceEnabled('hook:after_tool_call.trajectory');
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toBeDefined();
+    });
+
+    it('returns reason when surface not found', () => {
+      const result = isSurfaceEnabled('hook:nonexistent_hook');
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toContain('not found in registry');
+    });
+
+    it('allows override for quiet surface', () => {
+      const result = isSurfaceEnabled('hook:after_tool_call.trajectory', {
+        'hook:after_tool_call.trajectory': true,
+      });
+      expect(result.enabled).toBe(true);
+    });
+
+    it('ignores non-boolean override', () => {
+      const result = isSurfaceEnabled('hook:before_prompt_build', {
+        'hook:before_prompt_build': 'yes' as unknown as boolean,
+      });
+      expect(result.enabled).toBe(true);
+    });
+
+    it('cannot disable core surface', () => {
+      const result = isSurfaceEnabled('hook:before_prompt_build', {
+        'hook:before_prompt_build': false,
+      });
+      expect(result.enabled).toBe(true);
+      expect(result.reason).toContain('core');
+    });
+
+    it('returns disabledReason for disabled surface', () => {
+      const result = isSurfaceEnabled('service:evolution-worker');
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toContain('evolution_worker');
+    });
+  });
+
+  describe('guardHook', () => {
+    beforeEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('returns original handler for enabled surface', () => {
+      const mockHandler = vi.fn().mockReturnValue('result');
+      const guarded = guardHook('hook:before_prompt_build', undefined, mockHandler);
+      const result = guarded({}, {});
+      expect(mockHandler).toHaveBeenCalled();
+      expect(result).toBe('result');
+    });
+
+    it('returns no-op for disabled surface without logger', () => {
+      const mockHandler = vi.fn();
+      const guarded = guardHook('hook:after_tool_call.trajectory', undefined, mockHandler);
+      const result = guarded({}, {});
+      expect(mockHandler).not.toHaveBeenCalled();
+      expect(result).toBeUndefined();
+    });
+
+    it('logs when surface is disabled with logger', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const mockHandler = vi.fn();
+      const guarded = guardHook('hook:after_tool_call.trajectory', mockLogger, mockHandler);
+      guarded({}, {});
+      expect(mockLogger.info).toHaveBeenCalled();
+      expect(mockHandler).not.toHaveBeenCalled();
+    });
+
+    it('does not log for enabled surface', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const mockHandler = vi.fn();
+      const guarded = guardHook('hook:before_prompt_build', mockLogger, mockHandler);
+      guarded({}, {});
+      expect(mockLogger.info).not.toHaveBeenCalled();
+    });
+
+    it('guards unknown surface with not-found reason', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const guarded = guardHook('hook:unknown_hook', mockLogger, vi.fn());
+      guarded({}, {});
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('not found in registry'),
+      );
+    });
+  });
+
+  describe('guardService', () => {
+    beforeEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('returns original service for enabled surface', () => {
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('hook:before_prompt_build', mockService);
+      expect(result).toBe(mockService);
+    });
+
+    it('returns null for disabled surface without logger', () => {
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('hook:after_tool_call.trajectory', mockService);
+      expect(result).toBeNull();
+    });
+
+    it('logs when surface is disabled with logger', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('hook:after_tool_call.trajectory', mockService, mockLogger);
+      expect(result).toBeNull();
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('SKIP service'),
+      );
+    });
+
+    it('returns null for unknown surface', () => {
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('service:nonexistent', mockService);
+      expect(result).toBeNull();
+    });
+  });
+});

package/tests/core/workspace-guidance-migrator.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import type { Dirent } from 'fs';
+import type { OpenClawPluginApi } from '../../src/openclaw-sdk.js';
+
+const mockFs = {
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+  writeFileSync: vi.fn(),
+  readdirSync: vi.fn(),
+};
+
+vi.mock('fs', () => mockFs);
+
+const WORKSPACE_GUIDANCE_MIGRATOR_PATH = '../../src/core/workspace-guidance-migrator.js';
+
+describe('workspace-guidance-migrator', () => {
+  let migrateStaleWorkspaceGuidance: (api: OpenClawPluginApi, workspaceDir: string) => {
+    migratedFiles: string[];
+    skippedFiles: string[];
+    errors: { file: string; error: string }[];
+  };
+
+  const mockLogger = {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  };
+
+  const mockApi = {
+    logger: mockLogger,
+  } as unknown as OpenClawPluginApi;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    vi.resetModules();
+
+    mockFs.existsSync.mockReturnValue(true);
+    mockFs.readFileSync.mockReturnValue('');
+    mockFs.writeFileSync.mockReturnValue(undefined);
+    mockFs.readdirSync.mockReturnValue([]);
+
+    const module = await import(WORKSPACE_GUIDANCE_MIGRATOR_PATH);
+    migrateStaleWorkspaceGuidance = module.migrateStaleWorkspaceGuidance;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('migrateStaleWorkspaceGuidance', () => {
+    it('skips files that do not exist', () => {
+      mockFs.existsSync.mockReturnValue(false);
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles).toEqual([]);
+      expect(result.skippedFiles).toEqual([]);
+      expect(result.errors).toEqual([]);
+    });
+
+    it('skips files with no stale guidance', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue('# Clean AGENTS.md\nNo stale references here.');
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles).toEqual([]);
+      expect(result.skippedFiles.length).toBeGreaterThan(0);
+      expect(result.errors).toEqual([]);
+    });
+
+    it('migrates AGENTS.md with stale guidance', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(
+        '# Agent Instructions\nPhysical interception ensures safety.',
+      );
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles.some(f => f.includes('AGENTS.md'))).toBe(true);
+      expect(result.skippedFiles.some(f => f.includes('MEMORY.md'))).toBe(true);
+    });
+
+    it('creates backup before migration', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(
+        '# Agent Instructions\nPhysical interception ensures safety.',
+      );
+
+      migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      const backupCalls = mockFs.writeFileSync.mock.calls.filter(
+        (call: unknown[]) => String(call[0]).includes('.pre-pri286.bak'),
+      );
+      expect(backupCalls.length).toBeGreaterThan(0);
+    });
+
+    it('logs migration progress', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(
+        '# Agent Instructions\nPhysical interception ensures safety.',
+      );
+
+      migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('[PD:GuidanceMigration]'),
+      );
+    });
+
+    it('handles read errors gracefully', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockImplementation(() => {
+        throw new Error('Read error');
+      });
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.errors.length).toBeGreaterThan(0);
+      expect(result.errors[0].error).toContain('Failed to read file content');
+    });
+
+    it('handles write errors and restores original', () => {
+      const originalContent = '# Agent Instructions\nPhysical interception ensures safety.';
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(originalContent);
+
+      let callCount = 0;
+      mockFs.writeFileSync.mockImplementation((path: string, content: string) => {
+        callCount++;
+        if (path.includes('.pre-pri286.bak')) return;
+        if (callCount === 2) {
+          expect(content).toBe(originalContent);
+          return;
+        }
+        throw new Error('Write error');
+      });
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.errors.length).toBeGreaterThan(0);
+      expect(callCount).toBeGreaterThanOrEqual(2);
+    });
+
+    it('skips non-guidance files', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue('# Random Content\nNo guidance here.');
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles).toEqual([]);
+    });
+
+    it('discovers skill files in .principles/skills directory', () => {
+      mockFs.existsSync.mockImplementation((p: string) => {
+        if (String(p).includes('.principles/skills')) return true;
+        return false;
+      });
+      mockFs.readdirSync.mockReturnValue([
+        { isDirectory: () => true, name: 'admin' },
+        { isDirectory: () => true, name: 'reflection' },
+      ] as Dirent[]);
+      mockFs.readFileSync.mockReturnValue(
+        'Ensure `PLAN.md` contains `## Target Files` heading.',
+      );
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles.length).toBeGreaterThan(0);
+    });
+
+    it('handles empty workspace directory', () => {
+      mockFs.existsSync.mockReturnValue(false);
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles).toEqual([]);
+      expect(result.skippedFiles).toEqual([]);
+      expect(result.errors).toEqual([]);
+    });
+
+    it('handles skills directory read error gracefully', () => {
+      mockFs.existsSync.mockImplementation((p: string) => {
+        if (String(p).includes('.principles/skills')) return true;
+        return false;
+      });
+      mockFs.readdirSync.mockImplementation(() => {
+        throw new Error('Directory read error');
+      });
+      mockFs.readFileSync.mockReturnValue(
+        '# Agent Instructions\nPhysical interception ensures safety.',
+      );
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.errors.length).toBeGreaterThan(0);
+    });
+  });
+});