principles-disciple 1.86.0 → 1.88.0

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);
+    });
   });
 });

package/tests/service/correction-observer-service.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import * as yaml from 'js-yaml';
 import { WorkspaceContext } from '../../src/core/workspace-context.js';
 
 const mockLearner = {
@@ -35,6 +36,89 @@ vi.mock('../../src/service/keyword-optimization-service.js', () => ({
   KeywordOptimizationService: { get: vi.fn(() => mockOptimizationService) },
 }));
 
+// PRI-307: Mock the pd-config-loader instead of @principles/core/runtime-v2
+// The service now reads .pd/config.yaml via resolveObserverConfig
+vi.mock('../../src/core/pd-config-loader.js', () => {
+  return {
+    loadPdConfigForPlugin: vi.fn(() => ({
+      ok: true,
+      effective: {
+        config: {
+          version: 1,
+          features: {
+            prompt: { category: 'core', enabled: true },
+            code_tool_hook: { category: 'core', enabled: true },
+            defer_archive: { category: 'core', enabled: true },
+            correction_observer: { category: 'quiet', enabled: true },
+            empathy_observer: { category: 'quiet', enabled: false },
+          },
+          runtimeProfiles: {
+            'openclaw.default': { type: 'openclaw', source: 'default' },
+            'pd.anthropic-sonnet': { type: 'pi-ai', provider: 'anthropic', model: 'claude-3-5-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY', timeoutMs: 30000 },
+          },
+          internalAgents: {
+            defaultRuntime: 'openclaw.default',
+            agents: {
+              diagnostician: { enabled: true },
+              dreamer: { enabled: true },
+              scribe: { enabled: true },
+              artificer: { enabled: true },
+              philosopher: { enabled: false },
+              evaluator: { enabled: false },
+              rolloutReviewer: { enabled: false },
+              trainer: { enabled: false },
+              correctionObserver: { enabled: true, runtimeProfile: 'pd.anthropic-sonnet' },
+              empathyObserver: { enabled: false },
+            },
+          },
+        },
+        warnings: [],
+      },
+      source: 'defaults',
+      configPath: '.pd/config.yaml',
+      warnings: [],
+      errors: [],
+    })),
+    loadFeatureFlagFromConfig: vi.fn(() => ({ enabled: true, source: 'defaults' })),
+    resolveObserverConfig: vi.fn((_workspaceDir: string, flagId: string, _agentName: string) => {
+      // Default: return disabled for correction_observer (no config file in test tmp dirs)
+      if (flagId === 'correction_observer') {
+        return {
+          enabled: true,
+          readiness: 'not_ready',
+          source: 'defaults',
+          reason: 'pi-ai profile configured with apiKeyEnv',
+          nextAction: 'Run pd runtime probe',
+          runtimeProfileId: 'pd.anthropic-sonnet',
+          runtimeProfileType: 'pi-ai',
+          apiKeyEnv: 'ANTHROPIC_API_KEY',
+          apiKeyPresent: !!process.env.ANTHROPIC_API_KEY,
+          provider: 'anthropic',
+          model: 'claude-3-5-sonnet',
+          timeoutMs: 30000,
+          baseUrl: null,
+        };
+      }
+      return {
+        enabled: false,
+        readiness: 'disabled',
+        source: 'defaults',
+        reason: `${flagId} is disabled`,
+        nextAction: `Set features.${flagId}.enabled=true in .pd/config.yaml`,
+        runtimeProfileId: null,
+        runtimeProfileType: null,
+        apiKeyEnv: null,
+        apiKeyPresent: false,
+        provider: null,
+        model: null,
+        timeoutMs: null,
+        baseUrl: null,
+      };
+    }),
+    getPdConfigPath: vi.fn((workspaceDir: string) => path.join(workspaceDir, '.pd', 'config.yaml')),
+  };
+});
+
 const mockDispatch = vi.fn().mockResolvedValue({
   updated: true,
   summary: 'Keyword store optimized',
@@ -45,23 +129,12 @@ const mockRegister = vi.fn();
 
 vi.mock('@principles/core/runtime-v2', () => {
   return {
-    WorkflowFunnelLoader: class {
-      getFunnel = vi.fn(() => ({
-        policy: {
-          runtimeKind: 'pi-ai',
-          provider: 'anthropic',
-          model: 'anthropic/claude-3-5-sonnet',
-          apiKeyEnv: 'ANTHROPIC_API_KEY',
-          timeoutMs: 30000,
-        }
-      }));
-    },
     PiAiRuntimeAdapter: class {},
     CorrectionObserver: class {},
     AgentScheduler: class {
       register = mockRegister;
       dispatch = mockDispatch;
-    }
+    },
   };
 });
 
@@ -330,12 +403,12 @@ describe('runCorrectionObserverCycle — Independent Execution', () => {
   });
 });
 
-describe('resolveCorrectionObserver — Configuration Resolution', () => {
+describe('resolveCorrectionObserver — Configuration Resolution (PRI-307)', () => {
   beforeEach(() => {
     vi.clearAllMocks();
   });
 
-  it('returns observer when API key env is set with mocked policy', async () => {
+  it('returns observer when API key env is set with pi-ai profile', async () => {
     const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-corr-resolve-'));
     const stateDir = path.join(workspaceDir, '.state');
     fs.mkdirSync(stateDir, { recursive: true });
@@ -348,7 +421,7 @@ describe('resolveCorrectionObserver — Configuration Resolution', () => {
       const wctx = WorkspaceContext.fromHookContext({ workspaceDir });
       const result = resolveCorrectionObserver(wctx, logger as any);
 
-      // With mocked WorkflowFunnelLoader returning valid policy, should return observer
+      // With mocked resolveObserverConfig returning enabled + not_ready, should return observer
       expect(result).not.toBeNull();
     } finally {
       delete process.env.ANTHROPIC_API_KEY;
@@ -356,23 +429,76 @@ describe('resolveCorrectionObserver — Configuration Resolution', () => {
     }
   });
 
-  it('returns observer when workflows.yaml provides valid policy', async () => {
-    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-corr-policy-'));
+  it('returns null when observer is disabled in config', async () => {
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-corr-disabled-'));
     const stateDir = path.join(workspaceDir, '.state');
     fs.mkdirSync(stateDir, { recursive: true });
 
-    process.env.ANTHROPIC_API_KEY = 'test-key';
+    const logger = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() };
+
+    // Override the mock to return disabled
+    const { resolveObserverConfig } = await import('../../src/core/pd-config-loader.js');
+    vi.mocked(resolveObserverConfig).mockReturnValueOnce({
+      enabled: false,
+      readiness: 'disabled',
+      source: 'defaults',
+      reason: 'correction_observer is disabled in .pd/config.yaml',
+      nextAction: 'Set features.correction_observer.enabled=true in .pd/config.yaml to enable',
+      runtimeProfileId: null,
+      runtimeProfileType: null,
+      apiKeyEnv: null,
+      apiKeyPresent: false,
+      provider: null,
+      model: null,
+      timeoutMs: null,
+      baseUrl: null,
+    });
+
+    try {
+      const wctx = WorkspaceContext.fromHookContext({ workspaceDir });
+      const result = resolveCorrectionObserver(wctx, logger as any);
+
+      expect(result).toBeNull();
+    } finally {
+      safeRmDir(workspaceDir);
+    }
+  });
+
+  it('returns null when observer needs setup (no API key)', async () => {
+    const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-corr-needs-setup-'));
+    const stateDir = path.join(workspaceDir, '.state');
+    fs.mkdirSync(stateDir, { recursive: true });
 
     const logger = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() };
 
+    // Override the mock to return needs_setup
+    const { resolveObserverConfig } = await import('../../src/core/pd-config-loader.js');
+    vi.mocked(resolveObserverConfig).mockReturnValueOnce({
+      enabled: true,
+      readiness: 'needs_setup',
+      source: 'defaults',
+      reason: "Environment variable 'ANTHROPIC_API_KEY' is not set or empty",
+      nextAction: 'Set the environment variable ANTHROPIC_API_KEY with a valid API key',
+      runtimeProfileId: 'pd.anthropic-sonnet',
+      runtimeProfileType: 'pi-ai',
+      apiKeyEnv: 'ANTHROPIC_API_KEY',
+      apiKeyPresent: false,
+      provider: 'anthropic',
+      model: 'claude-3-5-sonnet',
+      timeoutMs: 30000,
+      baseUrl: null,
+    });
+
     try {
       const wctx = WorkspaceContext.fromHookContext({ workspaceDir });
       const result = resolveCorrectionObserver(wctx, logger as any);
 
-      // With mocked WorkflowFunnelLoader returning valid policy, should return observer
-      expect(result).not.toBeNull();
+      expect(result).toBeNull();
+      // Should log the needs_setup reason, not noisy "no API key" cycling
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('ANTHROPIC_API_KEY')
+      );
     } finally {
-      delete process.env.ANTHROPIC_API_KEY;
       safeRmDir(workspaceDir);
     }
   });

package/tests/service/evolution-worker.correction-observer.test.ts

@@ -14,7 +14,7 @@ describe('Correction Observer Ownership — Feature Flag & Surface Registry Cons
     const result = computeEffectiveFlags(
       { correction_observer: { enabled: false } },
       DEFAULT_FEATURE_FLAGS,
-      '.pd/feature-flags.yaml',
+      '.pd/config.yaml',
     );
     expect(result.flags['correction_observer'].enabled).toBe(false);
     expect(result.warnings).not.toContain(expect.stringContaining('core flag cannot be disabled'));