principles-disciple 1.86.0 → 1.87.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.86.0",
+  "version": "1.87.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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

package/src/core/surface-guard.ts

@@ -15,6 +15,53 @@ export interface SurfaceGuardResult {
   warnings: string[];
 }
 
+// Surface-level once-only log state (PRI-298).
+// The first time a quiet/non-core surface guard actually fires in this
+// process, the disabled reason is emitted once. Subsequent fires for the
+// same surfaceId are still observable (the no-op handler preserves
+// behaviour) but no longer flood the log. Fresh processes start with an
+// empty set, so each plugin load gets one observable skip per surface.
+//
+// The Set is only updated when the log was actually emitted, so passing
+// `undefined` for the logger on a quiet first fire does NOT consume the
+// one-shot slot — a later registration that supplies a logger still gets
+// the first-fire reason (PRI-298 / ERR-002).
+const loggedSkipSurfaces = new Set<string>();
+
+type LoggerLike = { info?: (msg: string) => void; debug?: (msg: string) => void };
+
+/**
+ * Emit the disabled-reason log line for `surfaceId` at most once per
+ * process. Returns true if the log was emitted, false if it was suppressed
+ * (already logged, or no logger available). Only marks the surface as
+ * logged when the log was actually written, so a missing logger on first
+ * call does not consume the one-shot slot.
+ */
+function logSkipOnce(
+  surfaceId: string,
+  logger: LoggerLike | undefined,
+  message: string,
+): boolean {
+  if (loggedSkipSurfaces.has(surfaceId)) {
+    return false;
+  }
+  if (!logger?.info) {
+    return false;
+  }
+  loggedSkipSurfaces.add(surfaceId);
+  logger.info(message);
+  return true;
+}
+
+/**
+ * Reset the per-process surface-guard skip log bookkeeping. Intended for tests
+ * that need to assert on the first-fire log without cross-test pollution.
+ * Not part of the production API surface; do not call from runtime code.
+ */
+export function __resetSurfaceGuardSkipLogStateForTests(): void {
+  loggedSkipSurfaces.clear();
+}
+
 export function checkSurfaceGuard(): SurfaceGuardResult {
   const validation = validateSurfaceRegistry(PLUGIN_SURFACE_REGISTRY);
   const violations: string[] = [];
@@ -98,7 +145,7 @@ 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,
+  logger: LoggerLike | undefined,
   handler: HookHandler<E, C, R>,
 ): HookHandler<E, C, R> {
   const check = isSurfaceEnabled(surfaceId);
@@ -106,8 +153,15 @@ export function guardHook<E, C, R>(
     return handler;
   }
   const reason = check.reason ?? 'surface not enabled';
+  // Log on the first ACTUAL no-op invocation, not at construction time
+  // (PRI-298). Construction-time logging would emit a `SKIP` line at
+  // plugin startup for every registered quiet hook, regardless of
+  // whether the hook ever fires — which is exactly the startup log
+  // noise this change is meant to prevent. The one-shot is consumed only
+  // when the log was actually written, so `undefined` logger on first
+  // call does not eat the slot.
   return (_event: E, _ctx: C): R | Promise<R> => {
-    logger?.info?.(`[PD:surface-guard] SKIP ${surfaceId}: ${reason}`);
+    logSkipOnce(surfaceId, logger, `[PD:surface-guard] SKIP ${surfaceId}: ${reason}`);
     return undefined as R;
   };
 }
@@ -115,14 +169,18 @@ export function guardHook<E, C, R>(
 export function guardService<T extends OpenClawPluginService>(
   surfaceId: string,
   service: T,
-  logger?: { info?: (msg: string) => void; debug?: (msg: string) => void },
+  logger?: LoggerLike,
 ): 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}`);
+  // guardService is called once per service during plugin registration,
+  // so the once-only check fires on the registration call itself. The
+  // shared helper makes the consumption rule identical to guardHook:
+  // a missing logger on first call does not consume the one-shot.
+  logSkipOnce(surfaceId, logger, `[PD:surface-guard] SKIP service ${surfaceId}: ${reason}`);
   return null;
 }
 

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

@@ -6,11 +6,18 @@ import {
   guardService,
   getSurfaceIdForHook,
   getSurfaceIdForService,
+  __resetSurfaceGuardSkipLogStateForTests,
 } 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', () => {
+  beforeEach(() => {
+    // Each test starts with a clean surface-guard skip log state so the
+    // first-fire assertions are deterministic (PRI-298).
+    __resetSurfaceGuardSkipLogStateForTests();
+    vi.clearAllMocks();
+  });
   describe('getSurfaceIdForHook', () => {
     it('generates correct surface id without label', () => {
       expect(getSurfaceIdForHook('before_tool_call')).toBe('hook:before_tool_call');
@@ -144,6 +151,39 @@ describe('surface-guard', () => {
       expect(mockHandler).not.toHaveBeenCalled();
     });
 
+    it('does not log at guardHook construction time (PRI-298 / chatgpt P2)', () => {
+      // Registering a guard for a quiet hook must not emit the SKIP line on
+      // its own; the log fires only when the returned no-op is actually
+      // invoked. Plugin startup that registers a dozen quiet hooks would
+      // otherwise log a dozen SKIP lines before any real traffic.
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      guardHook('hook:after_tool_call.trajectory', mockLogger, vi.fn());
+      expect(mockLogger.info).not.toHaveBeenCalled();
+    });
+
+    it('logger undefined on first fire does not consume the one-shot slot (PRI-298 / coderabbit Major)', () => {
+      // First call has no logger — the no-op still suppresses the handler,
+      // and the once-only slot is preserved for a later call that does
+      // have a logger.
+      const handler1 = guardHook('hook:after_tool_call.trajectory', undefined, vi.fn());
+      handler1({}, {});
+
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const handler2 = guardHook('hook:after_tool_call.trajectory', mockLogger, vi.fn());
+      handler2({}, {});
+
+      // Only the second call (which had a logger) should have emitted a log.
+      expect(mockLogger.info).toHaveBeenCalledTimes(1);
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('[PD:surface-guard] SKIP hook:after_tool_call.trajectory'),
+      );
+
+      // A third call should now be silent (slot consumed by the second call).
+      const handler3 = guardHook('hook:after_tool_call.trajectory', mockLogger, vi.fn());
+      handler3({}, {});
+      expect(mockLogger.info).toHaveBeenCalledTimes(1);
+    });
+
     it('does not log for enabled surface', () => {
       const mockLogger = { info: vi.fn(), debug: vi.fn() };
       const mockHandler = vi.fn();
@@ -160,6 +200,45 @@ describe('surface-guard', () => {
         expect.stringContaining('not found in registry'),
       );
     });
+
+    it('logs once on first fire and stays silent on subsequent fires (PRI-298 rate-limit)', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const mockHandler = vi.fn();
+      const guarded = guardHook('hook:after_tool_call.trajectory', mockLogger, mockHandler);
+
+      // First fire: log is emitted once with the disabled reason.
+      guarded({}, {});
+      expect(mockLogger.info).toHaveBeenCalledTimes(1);
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('[PD:surface-guard] SKIP hook:after_tool_call.trajectory'),
+      );
+
+      // Subsequent fires on the same surfaceId: no further log noise, but the
+      // handler is still suppressed (observability remains: the no-op returns
+      // undefined; the surface is still classified as disabled).
+      for (let i = 0; i < 5; i += 1) {
+        guarded({}, {});
+      }
+      expect(mockLogger.info).toHaveBeenCalledTimes(1);
+      expect(mockHandler).not.toHaveBeenCalled();
+    });
+
+    it('logs first fire per surfaceId independently (one log per quiet surface)', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const handler1 = guardHook('hook:after_tool_call.trajectory', mockLogger, vi.fn());
+      const handler2 = guardHook('hook:llm_output.trajectory', mockLogger, vi.fn());
+      const handler3 = guardHook('hook:subagent_spawning', mockLogger, vi.fn());
+
+      handler1({}, {});
+      handler2({}, {});
+      handler3({}, {});
+
+      expect(mockLogger.info).toHaveBeenCalledTimes(3);
+      const calls = mockLogger.info.mock.calls.map(c => String(c[0]));
+      expect(calls.some(c => c.includes('hook:after_tool_call.trajectory'))).toBe(true);
+      expect(calls.some(c => c.includes('hook:llm_output.trajectory'))).toBe(true);
+      expect(calls.some(c => c.includes('hook:subagent_spawning'))).toBe(true);
+    });
   });
 
   describe('guardService', () => {
@@ -194,5 +273,68 @@ describe('surface-guard', () => {
       const result = guardService('service:nonexistent', mockService);
       expect(result).toBeNull();
     });
+
+    it('logs once per service surface on first registration (PRI-298 rate-limit)', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const service: OpenClawPluginService = { id: 'test-service' };
+
+      // First registration call: the disabled reason is logged once.
+      const first = guardService('service:trajectory', service, mockLogger);
+      expect(first).toBeNull();
+      expect(mockLogger.info).toHaveBeenCalledTimes(1);
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('SKIP service service:trajectory'),
+      );
+
+      // Subsequent guardService calls for the same surfaceId stay silent.
+      guardService('service:trajectory', service, mockLogger);
+      guardService('service:trajectory', service, mockLogger);
+      expect(mockLogger.info).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('PRI-298 disabledReason copy', () => {
+    it('no quiet surface disabledReason references "Story A" or "Story A\'"', () => {
+      const quietOrNonCore = PLUGIN_SURFACE_REGISTRY.filter(
+        s => s.category === 'quiet' || s.category === 'gone' || s.category === 'legacy_retire',
+      );
+      expect(quietOrNonCore.length).toBeGreaterThan(0);
+      for (const surface of quietOrNonCore) {
+        expect(surface.disabledReason).toBeDefined();
+        // MVP residue that should not appear in production log copy.
+        expect(surface.disabledReason).not.toMatch(/Story A/);
+        expect(surface.disabledReason).not.toMatch(/MVP\s*验收/);
+        expect(surface.disabledReason).not.toMatch(/测试任务/);
+      }
+    });
+
+    it('trajectory hook disabledReason is opt-in and ADR-anchored (PRI-298)', () => {
+      const trajectory = PLUGIN_SURFACE_REGISTRY.find(
+        s => s.id === 'hook:after_tool_call.trajectory',
+      );
+      expect(trajectory?.disabledReason).toBeDefined();
+      const reason = trajectory!.disabledReason!.toLowerCase();
+      // Quiet hook copy is opt-in / opt-out anchored on a real ADR section
+      // (no MVP-phase residue, no promise of a feature-flag override that
+      // the production guard path does not actually consume — chatgpt P2).
+      expect(reason).toContain('opt-in');
+      expect(reason).toContain('default off');
+      expect(reason).toMatch(/adr-?0014/);
+    });
+
+    it('no quiet surface disabledReason promises a feature flag override (PRI-298 / chatgpt P2)', () => {
+      // The runtime guard path (`isSurfaceEnabled(surfaceId)` with no
+      // overrides argument) does not consume `.pd/feature-flags.yaml`, so
+      // telling operators to "enable via feature flag override" would be
+      // an impossible next action. Quiet copy must describe the surface
+      // honestly without pointing to a non-existent override path.
+      const quiet = PLUGIN_SURFACE_REGISTRY.filter(s => s.category === 'quiet');
+      expect(quiet.length).toBeGreaterThan(0);
+      for (const surface of quiet) {
+        const reason = surface.disabledReason!.toLowerCase();
+        expect(reason).not.toContain('enable via feature flag');
+        expect(reason).not.toMatch(/enable via .* override/);
+      }
+    });
   });
 });

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

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, beforeEach } from 'vitest';
 import * as fs from 'fs';
 import * as path from 'path';
 import {
@@ -109,6 +109,42 @@ describe('MVP Surface Registry Guard (PRI-289)', () => {
         expect(surface.disabledReason!.length).toBeGreaterThan(0);
       }
     });
+
+    it('no disabledReason references Story A / Story A\' / MVP 验收 / 测试任务 (PRI-298)', () => {
+      const disabled = PLUGIN_SURFACE_REGISTRY.filter(
+        s => s.category === 'quiet' || s.category === 'gone' || s.category === 'legacy_retire',
+      );
+      expect(disabled.length).toBeGreaterThan(0);
+      for (const surface of disabled) {
+        expect(surface.disabledReason).toBeDefined();
+        expect(surface.disabledReason).not.toMatch(/Story A/);
+        expect(surface.disabledReason).not.toMatch(/MVP\s*验收/);
+        expect(surface.disabledReason).not.toMatch(/测试任务/);
+      }
+    });
+
+    it('disabledReason copy is opt-in / feature-flag oriented for quiet surfaces (PRI-298)', () => {
+      const quiet = PLUGIN_SURFACE_REGISTRY.filter(s => s.category === 'quiet');
+      expect(quiet.length).toBeGreaterThan(0);
+      for (const surface of quiet) {
+        // Every quiet surface should anchor its reason in at least one
+        // stable, long-lived framing so the log copy can live in the product
+        // long after MVP. Acceptable framings:
+        //   - opt-in / disabled language (new quiet entries),
+        //   - feature-flag path (most existing entries),
+        //   - ADR reference (entries gated by a specific ADR section).
+        // What we still reject: ephemeral MVP-phase copy (covered by the
+        // Story A / MVP 验收 test above).
+        const reason = surface.disabledReason!.toLowerCase();
+        const hasOptInOrDisabled = /opt-?in|disabled/.test(reason);
+        const hasFeatureFlag = reason.includes('feature flag');
+        const hasAdrReference = /adr-?\d+|adr\s+\d+/.test(reason);
+        expect(
+          hasOptInOrDisabled || hasFeatureFlag || hasAdrReference,
+          `quiet surface ${surface.id} disabledReason must reference opt-in, feature flag, or an ADR: "${surface.disabledReason}"`,
+        ).toBe(true);
+      }
+    });
   });
 
   describe('api.on() registration coverage — every hook must be guarded', () => {
@@ -292,6 +328,17 @@ describe('MVP Surface Registry Guard (PRI-289)', () => {
   });
 
   describe('surface guard runtime', () => {
+    let resetSurfaceGuardLogState: () => void;
+
+    beforeEach(async () => {
+      // Lazy import so the module state is freshly required per describe and
+      // we can reset the PRI-298 rate-limit bookkeeping before every runtime
+      // assertion that depends on the first-fire log firing.
+      const mod = await import('../../src/core/surface-guard.js');
+      resetSurfaceGuardLogState = mod.__resetSurfaceGuardSkipLogStateForTests;
+      resetSurfaceGuardLogState();
+    });
+
     it('checkSurfaceGuard passes with current registry', async () => {
       const { checkSurfaceGuard } = await import('../../src/core/surface-guard.js');
       const result = checkSurfaceGuard();
@@ -403,5 +450,88 @@ describe('MVP Surface Registry Guard (PRI-289)', () => {
       const guarded = guardService('service:nonexistent_service', service);
       expect(guarded).toBeNull();
     });
+
+    it('PRI-298 rate-limit: quiet surface logs once, not per invocation', 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);
+
+      // First invocation must surface the disabled reason.
+      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');
+
+      // Subsequent invocations on the same surfaceId stay silent.
+      for (let i = 0; i < 10; i += 1) {
+        guarded({} as never, {} as never);
+      }
+      expect(logs.length).toBe(1);
+    });
+
+    it('PRI-298 rate-limit: resetSurfaceGuardSkipLogStateForTests re-arms first-fire', 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);
+
+      // Additional fires on the same surface: still 1 log.
+      guarded({} as never, {} as never);
+      expect(logs.length).toBe(1);
+
+      // Reset the per-process bookkeeping (simulating a fresh process / test
+      // isolation). The next fire on a freshly-constructed guarded handler
+      // should log again.
+      resetSurfaceGuardLogState();
+      const guarded2 = guardHook('hook:after_tool_call.trajectory', logger, handler);
+      guarded2({} as never, {} as never);
+      expect(logs.length).toBe(2);
+    });
+
+    it('PRI-298 / chatgpt P2: guardHook does NOT log at construction time', async () => {
+      const { guardHook } = await import('../../src/core/surface-guard.js');
+      const logs: string[] = [];
+      const logger = { info: (msg: string) => { logs.push(msg); } };
+      // The act of constructing the guard must not emit a SKIP line. Plugin
+      // startup that registers 7 quiet hooks would otherwise log 7 SKIP
+      // lines before any real traffic.
+      guardHook('hook:after_tool_call.trajectory', logger, () => 'result');
+      expect(logs.length).toBe(0);
+
+      // The first INVOCATION is when the log fires (and only once).
+      const guarded = guardHook('hook:llm_output.trajectory', logger, () => 'result');
+      guarded({} as never, {} as never);
+      expect(logs.length).toBe(1);
+    });
+
+    it('PRI-298 / coderabbit Major: guardHook logger undefined on first fire does not consume the one-shot slot', async () => {
+      const { guardHook } = await import('../../src/core/surface-guard.js');
+
+      // First call: no logger. The no-op suppresses the handler, but the
+      // once-only slot is preserved (a missing logger must not eat the
+      // chance to surface the disabled reason later).
+      const handler1 = guardHook('hook:after_tool_call.trajectory', undefined, () => 'result');
+      handler1({} as never, {} as never);
+
+      // Second call: real logger. This is now the first log emission for
+      // this surfaceId.
+      const logs: string[] = [];
+      const logger = { info: (msg: string) => { logs.push(msg); } };
+      const handler2 = guardHook('hook:after_tool_call.trajectory', logger, () => 'result');
+      handler2({} as never, {} as never);
+      expect(logs.length).toBe(1);
+      expect(logs[0]).toContain('[PD:surface-guard] SKIP');
+
+      // Third call: slot is now consumed; the third call is silent.
+      const handler3 = guardHook('hook:after_tool_call.trajectory', logger, () => 'result');
+      handler3({} as never, {} as never);
+      expect(logs.length).toBe(1);
+    });
   });
 });