create-principles-disciple 1.77.0 → 1.78.0

package/plugin/dist/index.js

@@ -1,4 +1,7 @@
 import * as path from 'path';
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+import { computeEffectiveFlags, DEFAULT_FEATURE_FLAGS } from '@principles/core/runtime-v2';
 import { classifyTask } from './core/local-worker-routing.js';
 import { completeShadowObservation, recordShadowRouting } from './core/shadow-observation-registry.js';
 import { getCommandDescription } from './i18n/commands.js';
@@ -10,7 +13,7 @@ import { handleBeforeReset, handleBeforeCompaction, handleAfterCompaction } from
 import { handleLlmOutput } from './hooks/llm.js';
 import { handleSubagentEnded } from './hooks/subagent.js';
 import * as TrajectoryCollector from './hooks/trajectory-collector.js';
-import { handleInitStrategy, handleManageOkr } from './commands/strategy.js';
+import { handleInitStrategy } from './commands/strategy.js';
 import { handleBootstrapTools, handleResearchTools } from './commands/capabilities.js';
 import { handleThinkingOs } from './commands/thinking-os.js';
 import { handlePainCommand, handlePainReportCommand } from './commands/pain.js';
@@ -27,6 +30,7 @@ import { handleExportCommand } from './commands/export.js';
 import { handleSamplesCommand } from './commands/samples.js';
 import { handleWorkflowDebugCommand } from './commands/workflow-debug.js';
 import { EvolutionWorkerService } from './service/evolution-worker.js';
+import { CorrectionObserverService } from './service/correction-observer-service.js';
 import { TrajectoryService } from './service/trajectory-service.js';
 import { PDTaskService } from './core/pd-task-service.js';
 import { CentralSyncService } from './service/central-sync-service.js';
@@ -39,6 +43,7 @@ import { resolveCommandWorkspaceDir, resolveToolHookWorkspaceDirSafe } from './u
 import { computeRuntimeShadowTaskFingerprint, PD_LOCAL_PROFILES } from './utils/shadow-fingerprint.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();
 const HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION = 'verify gateway plugin activation and hook workspace binding; ' +
@@ -46,6 +51,89 @@ const HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION = 'verify gateway plugin activation
 // Map from childSessionKey → shadowObservationId
 // Used to complete shadow observations when subagent ends
 const pendingShadowObservations = new Map();
+// ── Feature Flag Loader (plugin I/O boundary) ─────────────────────────────
+// Reads workspace feature-flags.yaml and checks a specific flag.
+// Returns the flag definition with effective enabled state.
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function loadFeatureFlagFromWorkspace(workspaceDir, flagId, logger) {
+    const configPath = path.join(workspaceDir, '.pd', 'feature-flags.yaml');
+    if (!fs.existsSync(configPath)) {
+        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
+        const flag = flags.flags[flagId];
+        return { enabled: flag?.enabled ?? false, source: 'defaults' };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, 'utf8');
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        logger?.warn?.(`[PD:FeatureFlags] Feature flags unreadable: ${msg} — using defaults`);
+        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
+        const flag = flags.flags[flagId];
+        return { enabled: flag?.enabled ?? false, source: 'defaults' };
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+    }
+    catch (e) {
+        const parseMsg = e instanceof Error ? e.message : String(e);
+        logger?.warn?.(`[PD:FeatureFlags] Feature flags YAML parse error: ${parseMsg} — using defaults`);
+        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
+        const flag = flags.flags[flagId];
+        return { enabled: flag?.enabled ?? false, source: 'defaults' };
+    }
+    if (!isRecord(parsed)) {
+        logger?.warn?.(`[PD:FeatureFlags] Feature flags not a mapping — using defaults`);
+        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
+        const flag = flags.flags[flagId];
+        return { enabled: flag?.enabled ?? false, source: 'defaults' };
+    }
+    // parsed is now narrowed to Record<string, unknown> by isRecord guard
+    const parsedRecord = Object.create(null);
+    for (const key of Object.keys(parsed)) {
+        if (DANGEROUS_KEYS.has(key))
+            continue;
+        if (Object.hasOwn(parsed, key)) {
+            parsedRecord[key] = parsed[key];
+        }
+    }
+    const flags = computeEffectiveFlags(parsedRecord, DEFAULT_FEATURE_FLAGS, configPath);
+    const flag = flags.flags[flagId];
+    return { enabled: flag?.enabled ?? false, source: flags.source };
+}
+export function shouldStartEvolutionWorker(workspaceDir, logger) {
+    const flag = loadFeatureFlagFromWorkspace(workspaceDir, 'evolution_worker', logger);
+    if (flag.enabled) {
+        return { shouldStart: true, flagSource: flag.source, disabledInfo: null };
+    }
+    const disabledInfo = JSON.stringify({
+        reason: 'mvp_quiet_per_adr0014',
+        nextAction: 'set evolution_worker.enabled=true in .pd/feature-flags.yaml to enable',
+        featureFlag: 'evolution_worker',
+        boundedContext: 'legacy_evolution_worker',
+        flagSource: flag.source,
+    });
+    return { shouldStart: false, flagSource: flag.source, disabledInfo };
+}
+export function shouldStartCorrectionObserver(workspaceDir, logger) {
+    const flag = loadFeatureFlagFromWorkspace(workspaceDir, 'correction_observer', logger);
+    if (flag.enabled) {
+        return { shouldStart: true, flagSource: flag.source, disabledInfo: null };
+    }
+    const disabledInfo = JSON.stringify({
+        reason: 'correction_observer_disabled',
+        nextAction: 'set correction_observer.enabled=true in .pd/feature-flags.yaml to enable',
+        featureFlag: 'correction_observer',
+        boundedContext: 'correction_observer_service',
+        flagSource: flag.source,
+    });
+    return { shouldStart: false, flagSource: flag.source, disabledInfo };
+}
 const plugin = {
     name: "Principles Disciple",
     description: "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
@@ -67,9 +155,21 @@ 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 || 'en';
         // ── Hook: Prompt Building ──
-        api.on('before_prompt_build', async (event, ctx) => {
+        api.on('before_prompt_build', guardHook('hook:before_prompt_build', api.logger, async (event, ctx) => {
             const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_prompt_build');
             if (!workspaceDir) {
                 api.logger.error(`[PD:before_prompt_build] workspaceDir resolution failed. ` +
@@ -87,16 +187,39 @@ const plugin = {
                     ensureWorkspaceTemplates(api, workspaceDir, language);
                     SystemLogger.log(workspaceDir, 'SYSTEM_BOOT', `Principles Disciple online. Language: ${language}`);
                     // ── Start EvolutionWorker for THIS workspace ──
-                    // One EvolutionWorker per workspace so each agent's pain signals
-                    // are processed independently.
-                    EvolutionWorkerService.api = api;
-                    EvolutionWorkerService.start({
-                        config: api.config,
-                        workspaceDir,
-                        stateDir: path.join(workspaceDir, '.state'),
-                        logger: api.logger,
-                    });
-                    api.logger.info(`[PD] EvolutionWorker started for workspace: ${workspaceDir}`);
+                    // Gated behind evolution_worker feature flag (MVP-Quiet, default OFF per ADR-0014).
+                    const gate = shouldStartEvolutionWorker(workspaceDir, api.logger);
+                    if (gate.shouldStart) {
+                        EvolutionWorkerService.api = api;
+                        EvolutionWorkerService.start({
+                            config: api.config,
+                            workspaceDir,
+                            stateDir: path.join(workspaceDir, '.state'),
+                            logger: api.logger,
+                        });
+                        api.logger.info(`[PD] EvolutionWorker started for workspace: ${workspaceDir} (flag source: ${gate.flagSource})`);
+                    }
+                    else {
+                        // Structured observability per ERR-002: no silent skip
+                        api.logger.info(`[PD] EvolutionWorker NOT started for workspace: ${workspaceDir}. ${gate.disabledInfo}`);
+                        SystemLogger.log(workspaceDir, 'EVOLUTION_WORKER_DISABLED', gate.disabledInfo ?? '');
+                    }
+                    // ── Start CorrectionObserver for THIS workspace ──
+                    // MVP-Core per ADR-0014 amendment, independently owned (PRI-293).
+                    const corrGate = shouldStartCorrectionObserver(workspaceDir, api.logger);
+                    if (corrGate.shouldStart) {
+                        CorrectionObserverService.start({
+                            config: api.config,
+                            workspaceDir,
+                            stateDir: path.join(workspaceDir, '.state'),
+                            logger: api.logger,
+                        });
+                        api.logger.info(`[PD] CorrectionObserver started for workspace: ${workspaceDir} (flag source: ${corrGate.flagSource})`);
+                    }
+                    else {
+                        api.logger.info(`[PD] CorrectionObserver NOT started for workspace: ${workspaceDir}. ${corrGate.disabledInfo}`);
+                        SystemLogger.log(workspaceDir, 'CORRECTION_OBSERVER_DISABLED', corrGate.disabledInfo ?? '');
+                    }
                 }
                 const result = await handleBeforePromptBuild(event, { ...ctx, api: api, workspaceDir });
                 // Record success
@@ -114,9 +237,9 @@ const plugin = {
                 });
                 api.logger.error(`[PD] Error in before_prompt_build: ${String(err)}`);
             }
-        });
+        }));
         // ── Hook: Security Gate ──
-        api.on('before_tool_call', (event, ctx) => {
+        api.on('before_tool_call', guardHook('hook:before_tool_call', api.logger, (event, ctx) => {
             const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_tool_call');
             if (!workspaceDir) {
                 api.logger.error(`[PD:before_tool_call] workspaceDir resolution failed. ` +
@@ -142,9 +265,9 @@ const plugin = {
                 }, { flushImmediately: true });
                 api.logger.error(`[PD] Error in before_tool_call: ${String(err)}`);
             }
-        });
+        }));
         // ── Hook: Pain & Trust ──
-        api.on('after_tool_call', (event, ctx) => {
+        api.on('after_tool_call', guardHook('hook:after_tool_call', api.logger, (event, ctx) => {
             const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'after_tool_call');
             if (!workspaceDir) {
                 api.logger.error(`[PD:after_tool_call] workspaceDir resolution failed. ` +
@@ -169,9 +292,9 @@ const plugin = {
                 }, { flushImmediately: true });
                 api.logger.error(`[PD:EmpathyObserver] Error in after_tool_call: ${String(err)}`);
             }
-        });
+        }));
         // ── Hook: LLM Analysis ──
-        api.on('llm_output', (event, ctx) => {
+        api.on('llm_output', guardHook('hook:llm_output', api.logger, (event, ctx) => {
             const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'llm_output');
             if (!workspaceDir) {
                 api.logger.error(`[PD:llm_output] workspaceDir resolution failed. ` +
@@ -196,10 +319,10 @@ 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, ctx) => {
+        api.on('after_tool_call', guardHook('hook:after_tool_call.trajectory', api.logger, (event, ctx) => {
             try {
                 const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'trajectory.after_tool_call');
                 if (!workspaceDir)
@@ -210,8 +333,8 @@ const plugin = {
             catch (_err) {
                 // Non-critical: don't log, just skip
             }
-        });
-        api.on('llm_output', (event, ctx) => {
+        }));
+        api.on('llm_output', guardHook('hook:llm_output.trajectory', api.logger, (event, ctx) => {
             try {
                 const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'trajectory.llm_output');
                 if (!workspaceDir)
@@ -222,9 +345,9 @@ const plugin = {
             catch (_err) {
                 // Non-critical: don't log, just skip
             }
-        });
+        }));
         // ── Hook: Subagent Loop Closure ──
-        api.on('subagent_spawning', (event, _ctx) => {
+        api.on('subagent_spawning', guardHook('hook:subagent_spawning', api.logger, (event, _ctx) => {
             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.
@@ -262,8 +385,8 @@ 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, ctx) => {
+        }));
+        api.on('subagent_ended', guardHook('hook:subagent_ended', api.logger, (event, ctx) => {
             try {
                 // FIX (B): Never fall back to '.' — fail-fast with ERROR log if workspaceDir cannot be resolved.
                 const workspaceDir = resolveWorkspaceDirFromApi(api, undefined);
@@ -297,9 +420,9 @@ const plugin = {
             catch (err) {
                 api.logger.error(`[PD] Error in subagent_ended: ${String(err)}`);
             }
-        });
+        }));
         // ── Hook: Lifecycle ──
-        api.on('before_reset', (event, ctx) => {
+        api.on('before_reset', guardHook('hook:before_reset', api.logger, (event, ctx) => {
             const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_reset');
             if (!workspaceDir) {
                 api.logger.error(`[PD:before_reset] workspaceDir resolution failed. ` +
@@ -308,8 +431,8 @@ const plugin = {
                 return;
             }
             return handleBeforeReset(event, { ...ctx, workspaceDir });
-        });
-        api.on('before_compaction', (event, ctx) => {
+        }));
+        api.on('before_compaction', guardHook('hook:before_compaction', api.logger, (event, ctx) => {
             const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_compaction');
             if (!workspaceDir) {
                 api.logger.error(`[PD:before_compaction] workspaceDir resolution failed. ` +
@@ -318,8 +441,8 @@ const plugin = {
                 return;
             }
             return handleBeforeCompaction(event, { ...ctx, workspaceDir });
-        });
-        api.on('after_compaction', (event, ctx) => {
+        }));
+        api.on('after_compaction', guardHook('hook:after_compaction', api.logger, (event, ctx) => {
             const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'after_compaction');
             if (!workspaceDir) {
                 api.logger.error(`[PD:after_compaction] workspaceDir resolution failed. ` +
@@ -328,17 +451,28 @@ 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 guardedCorrectionObserver = guardService('service:correction-observer', CorrectionObserverService, api.logger);
+            if (guardedCorrectionObserver)
+                api.registerService(guardedCorrectionObserver);
+            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 ──
         // Register command with optional short alias
@@ -359,20 +493,9 @@ const plugin = {
             }
         };
         registerCommandWithAlias('pd-init', 'pdi', getCommandDescription('pd-init', language), (ctx) => handleInitStrategy(ctx));
-        registerCommandWithAlias('pd-okr', 'pdk', getCommandDescription('pd-okr', language), (ctx) => handleManageOkr(ctx));
         registerCommandWithAlias('pd-bootstrap', 'pdb', getCommandDescription('pd-bootstrap', language), (ctx) => handleBootstrapTools(ctx));
         registerCommandWithAlias('pd-research', 'pdr', getCommandDescription('pd-research', language), (ctx) => handleResearchTools(ctx));
         registerCommandWithAlias('pd-thinking', 'pdt', getCommandDescription('pd-thinking', language), (ctx) => handleThinkingOs(ctx), { acceptsArgs: true });
-        registerCommandWithAlias('pd-daily', 'pdd', getCommandDescription('pd-daily', language), () => ({
-            text: language === 'zh'
-                ? "请执行 pd-daily 技能来配置并发送进化日报。系统将引导你完成配置流程，包括发送时间、渠道和报告风格偏好。"
-                : "Please execute the pd-daily skill to configure and send your daily evolution report. The system will guide you through the configuration process."
-        }));
-        registerCommandWithAlias('pd-grooming', 'pdg', getCommandDescription('pd-grooming', language), () => ({
-            text: language === 'zh'
-                ? "请执行 pd-grooming 技能来执行大扫除。例如输入: '执行 pd-grooming 技能'"
-                : "Please execute the pd-grooming skill to clean up. For example: 'Execute pd-grooming skill'"
-        }));
         registerCommandWithAlias('pd-help', 'pdh', getCommandDescription('pd-help', language), () => {
             if (language === 'zh') {
                 return { text: `
@@ -388,10 +511,7 @@ const plugin = {
 ## 状态查询
 | 短命令 | 长命令 | 用途 |
 |--------|--------|------|
-| \`/pdk\` | \`/pd-okr\` | OKR 目标管理 |
 | \`/pdt\` | \`/pd-thinking\` | 思维模型管理 |
-| \`/pdd\` | \`/pd-daily\` | 进化日报 |
-| \`/pdg\` | \`/pd-grooming\` | 工作区清理 |
 
 ## 其他命令
 | 命令 | 用途 |
@@ -420,10 +540,7 @@ const plugin = {
 ## Status
 | Short | Full | Purpose |
 |-------|------|---------|
-| \`/pdk\` | \`/pd-okr\` | OKR goal management |
 | \`/pdt\` | \`/pd-thinking\` | Mental model management |
-| \`/pdd\` | \`/pd-daily\` | Evolution report |
-| \`/pdg\` | \`/pd-grooming\` | Workspace cleanup |
 
 ## Other Commands
 | Command | Purpose |
@@ -685,4 +802,6 @@ const plugin = {
     }
 };
 export { PrincipleTreeLedgerAdapter } from './core/principle-tree-ledger-adapter.js';
+/* istanbul ignore next — test exports for evolution worker gate */
+export { loadFeatureFlagFromWorkspace, isRecord };
 export default plugin;

package/plugin/dist/service/correction-observer-service.d.ts

@@ -0,0 +1,11 @@
+import type { OpenClawPluginServiceContext, PluginLogger } from '../openclaw-sdk.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+import { CorrectionObserver } from '@principles/core/runtime-v2';
+export interface CorrectionObserverServiceShape {
+    id: string;
+    start: (ctx: OpenClawPluginServiceContext) => void;
+    stop?: (ctx: OpenClawPluginServiceContext) => void;
+}
+export declare function resolveCorrectionObserver(wctx: WorkspaceContext, logger?: Pick<PluginLogger, 'info' | 'warn' | 'error' | 'debug'>): CorrectionObserver | null;
+export declare function runCorrectionObserverCycle(wctx: WorkspaceContext, logger: PluginLogger): Promise<void>;
+export declare const CorrectionObserverService: CorrectionObserverServiceShape;

package/plugin/dist/service/correction-observer-service.js

@@ -0,0 +1,172 @@
+import { WorkspaceContext } from '../core/workspace-context.js';
+import { TrajectoryRegistry } from '../core/trajectory.js';
+import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
+import { WorkflowFunnelLoader, PiAiRuntimeAdapter, CorrectionObserver, AgentScheduler, } from '@principles/core/runtime-v2';
+import { KeywordOptimizationService } from './keyword-optimization-service.js';
+import { SystemLogger } from '../core/system-logger.js';
+let correctionObserverTimeoutId = null;
+let correctionObserverStopped = false;
+const startedWorkspaces = new Set();
+const CORRECTION_OBSERVER_INTERVAL_MS = 15 * 60 * 1000;
+const CORRECTION_OBSERVER_INITIAL_DELAY_MS = 10_000;
+const CORRECTION_OBSERVER_MAX_RECENT_SESSIONS = 20;
+const CORRECTION_OBSERVER_MAX_PAYLOAD_SESSIONS = 5;
+export function resolveCorrectionObserver(wctx, logger) {
+    try {
+        const loader = new WorkflowFunnelLoader(wctx.stateDir);
+        const funnel = loader.getFunnel('pd-correction-observer');
+        const policy = funnel?.policy;
+        if (!policy || policy.runtimeKind !== 'pi-ai') {
+            logger?.debug?.('[PD:CorrectionObserver] workflows.yaml pd-correction-observer policy not found. Falling back to environment variables.');
+            const provider = process.env.PD_CORRECTION_PROVIDER || 'anthropic';
+            const model = process.env.PD_CORRECTION_MODEL || 'anthropic/claude-3-5-sonnet';
+            const apiKeyEnv = process.env.PD_CORRECTION_API_KEY_ENV || 'ANTHROPIC_API_KEY';
+            const baseUrl = process.env.PD_CORRECTION_BASE_URL;
+            if (!process.env[apiKeyEnv]) {
+                logger?.debug?.(`[PD:CorrectionObserver] API key env ${apiKeyEnv} is not set. Periodic optimization disabled.`);
+                return null;
+            }
+            const adapter = new PiAiRuntimeAdapter({
+                provider,
+                model,
+                apiKeyEnv,
+                baseUrl,
+                workspace: wctx.workspaceDir,
+            });
+            return new CorrectionObserver({ runtimeAdapter: adapter });
+        }
+        const adapter = new PiAiRuntimeAdapter({
+            provider: String(policy.provider),
+            model: String(policy.model),
+            apiKeyEnv: String(policy.apiKeyEnv),
+            maxRetries: policy.maxRetries,
+            timeoutMs: policy.timeoutMs ?? 30_000,
+            baseUrl: policy.baseUrl,
+            workspace: wctx.workspaceDir,
+        });
+        return new CorrectionObserver({ runtimeAdapter: adapter }, { timeoutMs: policy.timeoutMs });
+    }
+    catch (err) {
+        logger?.warn?.(`[PD:CorrectionObserver] Failed to resolve CorrectionObserver: ${String(err)}`);
+        return null;
+    }
+}
+export async function runCorrectionObserverCycle(wctx, logger) {
+    try {
+        const observer = resolveCorrectionObserver(wctx, logger);
+        if (!observer) {
+            logger?.info?.('[PD:CorrectionObserver] Observer not resolved (no API key or config). Skipping cycle.');
+            return;
+        }
+        logger?.info?.('[PD:CorrectionObserver] Observer resolved. Initiating periodic optimization...');
+        const db = TrajectoryRegistry.get(wctx.workspaceDir);
+        const recentSessions = db.listRecentSessions({ limit: CORRECTION_OBSERVER_MAX_RECENT_SESSIONS });
+        const recentSessionIds = recentSessions.map(s => s.sessionId);
+        if (recentSessionIds.length === 0) {
+            logger?.info?.('[PD:CorrectionObserver] No recent sessions found. Skipping correction optimization.');
+            return;
+        }
+        const recentMessages = [];
+        for (const sId of recentSessionIds.slice(0, CORRECTION_OBSERVER_MAX_PAYLOAD_SESSIONS)) {
+            try {
+                const turns = db.listUserTurnsForSession(sId);
+                for (const t of turns) {
+                    if (t.rawExcerpt) {
+                        recentMessages.push(t.rawExcerpt);
+                    }
+                }
+            }
+            catch (turnErr) {
+                logger?.warn?.(`[PD:CorrectionObserver] Failed to load user turns for session ${sId}: ${String(turnErr)}`);
+            }
+        }
+        const learner = CorrectionCueLearner.get(wctx.stateDir);
+        const keywords = learner.getStore().keywords;
+        const keywordStoreSummary = {
+            totalKeywords: keywords.length,
+            terms: keywords.map(k => ({
+                term: k.term,
+                weight: k.weight,
+                hitCount: k.hitCount ?? 0,
+                truePositiveCount: k.truePositiveCount ?? 0,
+                falsePositiveCount: k.falsePositiveCount ?? 0,
+            })),
+        };
+        const optimizationService = KeywordOptimizationService.get(wctx.stateDir, wctx.workspaceDir, logger);
+        const trajectoryHistory = await optimizationService.buildTrajectoryHistory(recentSessionIds);
+        const payload = {
+            parentSessionId: 'correction-observer-service',
+            workspaceDir: wctx.workspaceDir,
+            keywordStoreSummary,
+            recentMessages,
+            trajectoryHistory,
+        };
+        const scheduler = new AgentScheduler();
+        scheduler.register({
+            agentId: 'correction-observer',
+            mode: 'realtime',
+            runner: observer,
+        });
+        logger?.info?.(`[PD:CorrectionObserver] Dispatching with ${trajectoryHistory.length} trajectory events, ${recentMessages.length} recent messages.`);
+        const result = await scheduler.dispatch('correction-observer', payload);
+        logger?.info?.(`[PD:CorrectionObserver] Completed: updated=${result.updated}, summary="${result.summary}"`);
+        if (result.updated) {
+            optimizationService.applyResult(result);
+        }
+    }
+    catch (err) {
+        const errMsg = `Correction observer cycle failed: ${String(err)}`;
+        logger?.warn?.(`[PD:CorrectionObserver] ${errMsg}`);
+        SystemLogger.log(wctx.workspaceDir, 'CORRECTION_OBSERVER_CYCLE_FAILED', errMsg);
+    }
+}
+export const CorrectionObserverService = {
+    id: 'principles-correction-observer',
+    start(ctx) {
+        const workspaceDir = ctx?.workspaceDir;
+        const logger = ctx?.logger || console;
+        if (!workspaceDir) {
+            if (logger)
+                logger.warn('[PD:CorrectionObserver] workspaceDir not found in service config. Correction observer disabled.');
+            return;
+        }
+        if (startedWorkspaces.has(workspaceDir)) {
+            if (logger)
+                logger.info(`[PD:CorrectionObserver] Already started for workspace: ${workspaceDir}. Skipping duplicate start.`);
+            return;
+        }
+        startedWorkspaces.add(workspaceDir);
+        correctionObserverStopped = false;
+        const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
+        if (logger)
+            logger.info(`[PD:CorrectionObserver] Starting with workspaceDir=${wctx.workspaceDir}, stateDir=${wctx.stateDir}`);
+        const interval = CORRECTION_OBSERVER_INTERVAL_MS;
+        async function runCycle() {
+            if (correctionObserverStopped)
+                return;
+            await runCorrectionObserverCycle(wctx, logger);
+            if (correctionObserverStopped)
+                return;
+            correctionObserverTimeoutId = setTimeout(runCycle, interval);
+            correctionObserverTimeoutId.unref();
+        }
+        correctionObserverTimeoutId = setTimeout(() => {
+            void runCycle().catch((err) => {
+                if (logger)
+                    logger.error(`[PD:CorrectionObserver] Startup cycle failed: ${String(err)}`);
+                if (correctionObserverStopped)
+                    return;
+                correctionObserverTimeoutId = setTimeout(runCycle, interval);
+                correctionObserverTimeoutId.unref();
+            });
+        }, CORRECTION_OBSERVER_INITIAL_DELAY_MS);
+        correctionObserverTimeoutId.unref();
+    },
+    stop(_ctx) {
+        correctionObserverStopped = true;
+        startedWorkspaces.clear();
+        if (correctionObserverTimeoutId)
+            clearTimeout(correctionObserverTimeoutId);
+        correctionObserverTimeoutId = null;
+    },
+};