principles-disciple 1.87.0 → 1.89.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.87.0",
+  "version": "1.89.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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

package/src/commands/pain.ts

@@ -7,6 +7,7 @@ import type { EmpathyEventStats } from '../types/event-types.js';
 import type { EvolutionLoopEvent } from '../core/evolution-types.js';
 import { computeHash } from '../utils/hashing.js';
 import { PainToPrincipleService, PrincipleTreeLedgerAdapter } from '@principles/core/runtime-v2';
+import { loadPdConfigForPlugin } from '../core/pd-config-loader.js';
 
 /**
  * Creates a visual progress bar (e.g., [██████░░░░])
@@ -310,12 +311,16 @@ export async function handlePainReportCommand(ctx: PluginCommandContext): Promis
 
   try {
     const ledgerAdapter = new PrincipleTreeLedgerAdapter({ stateDir: wctx.stateDir });
+    // PRI-306: Load .pd/config.yaml for config-driven runtime binding
+    const configResult = loadPdConfigForPlugin(wctx.workspaceDir);
     const service = new PainToPrincipleService({
       workspaceDir: wctx.workspaceDir,
       stateDir: wctx.stateDir,
       ledgerAdapter,
       owner: 'openclaw-plugin',
       autoIntakeEnabled: true,
+      effectiveConfig: configResult.effective,
+      getEnvVar: (name: string) => process.env[name],
     });
 
     const result = await service.recordPain({

package/src/core/pd-config-loader.ts

@@ -0,0 +1,400 @@
+/**
+ * PD Config Loader (Plugin I/O boundary) — PRI-307
+ *
+ * Reads `.pd/config.yaml`, validates via core, computes effective config.
+ * Replaces the old `.pd/feature-flags.yaml` and `.state/workflows.yaml` reading
+ * for plugin production paths.
+ *
+ * ADR-0016: PD owns exactly one user config file.
+ * - Missing config → defaults with nextAction
+ * - Malformed config → fail loud with errors and nextAction
+ * - No secrets in output
+ * - Observer disabled → no start / no noisy log cycling
+ * - Observer enabled + missing setup → structured needs_setup + nextAction
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import yaml from 'js-yaml';
+import {
+  validatePdConfig,
+  computeEffectivePdConfig,
+  computeFeatureFlagsFromConfig,
+  INTERNAL_AGENT_NAMES,
+} from '@principles/core/runtime-v2';
+import type {
+  EffectivePdConfig,
+  PdConfigValidationResult,
+  InternalAgentName,
+} from '@principles/core/runtime-v2';
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+export const PD_CONFIG_DIR = '.pd';
+export const PD_CONFIG_FILENAME = 'config.yaml';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type ObserverReadiness = 'disabled' | 'needs_setup' | 'ready' | 'not_ready' | 'config_malformed';
+
+export interface ObserverConfigResult {
+  /** Whether the observer feature is enabled in config */
+  enabled: boolean;
+  /** Observer readiness state */
+  readiness: ObserverReadiness;
+  /** Config source: 'defaults' | 'user_config' | 'malformed' */
+  source: string;
+  /** Reason for current state */
+  reason: string;
+  /** What the user should do next */
+  nextAction: string;
+  /** The runtime profile ID for this observer, if configured */
+  runtimeProfileId: string | null;
+  /** The runtime profile type, if configured */
+  runtimeProfileType: string | null;
+  /** The apiKeyEnv for the runtime profile, if applicable */
+  apiKeyEnv: string | null;
+  /** Whether the apiKeyEnv is present in process.env */
+  apiKeyPresent: boolean;
+  /** Provider name from runtime profile */
+  provider: string | null;
+  /** Model name from runtime profile */
+  model: string | null;
+  /** Timeout from runtime profile */
+  timeoutMs: number | null;
+  /** Base URL from runtime profile */
+  baseUrl: string | null;
+  /** Config validation errors (only present when readiness=config_malformed) */
+  configErrors?: Array<{ path: string; reason: string; nextAction: string }>;
+}
+
+export interface PluginConfigLoadResult {
+  ok: boolean;
+  effective: EffectivePdConfig;
+  source: 'defaults' | 'user_config' | 'malformed';
+  configPath: string;
+  warnings: string[];
+  errors: Array<{ path: string; reason: string; nextAction: string }>;
+}
+
+// ── Config Path ──────────────────────────────────────────────────────────────
+
+export function getPdConfigPath(workspaceDir: string): string {
+  return path.join(workspaceDir, PD_CONFIG_DIR, PD_CONFIG_FILENAME);
+}
+
+// ── Load PD Config ───────────────────────────────────────────────────────────
+
+/**
+ * Load and validate `.pd/config.yaml` from the workspace.
+ * Never throws on malformed input. Always provides a usable fallback.
+ */
+export function loadPdConfigForPlugin(workspaceDir: string): PluginConfigLoadResult {
+  const configPath = getPdConfigPath(workspaceDir);
+
+  // 1) Config file missing → use defaults
+  if (!fs.existsSync(configPath)) {
+    const effective = computeEffectivePdConfig(null);
+    return {
+      ok: true,
+      effective,
+      source: 'defaults',
+      configPath,
+      warnings: effective.warnings,
+      errors: [],
+    };
+  }
+
+  // 2) Read the file
+  let raw: string;
+  try {
+    raw = fs.readFileSync(configPath, 'utf8');
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const effective = computeEffectivePdConfig(null);
+    return {
+      ok: false,
+      effective,
+      source: 'malformed',
+      configPath,
+      warnings: [],
+      errors: [{ path: '', reason: `Failed to read .pd/config.yaml: ${message}`, nextAction: 'Check file permissions for .pd/config.yaml' }],
+    };
+  }
+
+  // 3) Parse YAML — treat as unknown (ERR-001)
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const effective = computeEffectivePdConfig(null);
+    return {
+      ok: false,
+      effective,
+      source: 'malformed',
+      configPath,
+      warnings: [],
+      errors: [{ path: '', reason: `YAML parse error in .pd/config.yaml: ${message}`, nextAction: 'Fix YAML syntax in .pd/config.yaml' }],
+    };
+  }
+
+  // 4) Validate via core (ERR-001, ERR-005: no `as` bypasses)
+  const validationResult: PdConfigValidationResult = validatePdConfig(parsed);
+
+  if (!validationResult.ok) {
+    const effective = computeEffectivePdConfig(null);
+    return {
+      ok: false,
+      effective,
+      source: 'malformed',
+      configPath,
+      warnings: [],
+      errors: validationResult.errors.map(e => ({
+        path: e.path,
+        reason: e.reason,
+        nextAction: e.nextAction,
+      })),
+    };
+  }
+
+  // 5) Compute effective config
+  const effective = computeEffectivePdConfig(validationResult.value);
+
+  return {
+    ok: true,
+    effective,
+    source: 'user_config',
+    configPath,
+    warnings: effective.warnings,
+    errors: [],
+  };
+}
+
+// ── Feature Flag from Config ─────────────────────────────────────────────────
+
+/**
+ * Get a single feature flag's enabled state from .pd/config.yaml.
+ * Replaces the old `loadFeatureFlagFromWorkspace` which read .pd/feature-flags.yaml.
+ */
+export function loadFeatureFlagFromConfig(
+  workspaceDir: string,
+  flagId: string,
+  logger?: { warn?: (msg: string) => void; info?: (msg: string) => void },
+): { enabled: boolean; source: string } {
+  const result = loadPdConfigForPlugin(workspaceDir);
+  const flags = computeFeatureFlagsFromConfig(result.effective);
+  const flag = flags.flags[flagId];
+
+  if (!result.ok) {
+    logger?.warn?.(`[PD:Config] Config validation failed: ${result.errors.map(e => e.reason).join('; ')} — using defaults`);
+  }
+
+  return {
+    enabled: flag?.enabled ?? false,
+    source: result.source,
+  };
+}
+
+// ── Observer Config Resolution ───────────────────────────────────────────────
+
+/**
+ * Resolve observer configuration from .pd/config.yaml.
+ *
+ * Returns structured state:
+ * - config_malformed: config file is invalid — no guessing, fail loud
+ * - disabled: observer feature flag is off OR agent.enabled=false → no start, no noisy logs
+ * - needs_setup: observer enabled but runtime profile missing, API key not set, or unsupported profile type
+ * - ready: observer enabled and fully configured (pi-ai with key present)
+ * - not_ready: observer enabled, API key present, but runtime availability unknown
+ */
+export function resolveObserverConfig(
+  workspaceDir: string,
+  observerFlagId: string,
+  observerAgentName: string,
+  _logger?: { warn?: (msg: string) => void; info?: (msg: string) => void; debug?: (msg: string) => void },
+): ObserverConfigResult {
+  const result = loadPdConfigForPlugin(workspaceDir);
+
+  // 0) Malformed config → fail loud, do NOT swallow as "disabled"
+  if (!result.ok) {
+    return {
+      enabled: false,
+      readiness: 'config_malformed',
+      source: 'malformed',
+      reason: `Config validation failed: ${result.errors.map(e => e.reason).join('; ')}`,
+      nextAction: result.errors[0]?.nextAction ?? 'Fix .pd/config.yaml and retry',
+      runtimeProfileId: null,
+      runtimeProfileType: null,
+      apiKeyEnv: null,
+      apiKeyPresent: false,
+      provider: null,
+      model: null,
+      timeoutMs: null,
+      baseUrl: null,
+      configErrors: result.errors,
+    };
+  }
+
+  const config = result.effective.config;
+
+  // 1) Check if the observer feature flag is enabled
+  const featureFlag = config.features[observerFlagId];
+  if (!featureFlag || !featureFlag.enabled) {
+    return {
+      enabled: false,
+      readiness: 'disabled',
+      source: result.source,
+      reason: `${observerFlagId} is disabled in .pd/config.yaml`,
+      nextAction: `Set features.${observerFlagId}.enabled=true in .pd/config.yaml to enable`,
+      runtimeProfileId: null,
+      runtimeProfileType: null,
+      apiKeyEnv: null,
+      apiKeyPresent: false,
+      provider: null,
+      model: null,
+      timeoutMs: null,
+      baseUrl: null,
+    };
+  }
+
+  // 2) Check if the agent itself is enabled (feature flag ≠ agent.enabled)
+  const knownNames: readonly string[] = INTERNAL_AGENT_NAMES;
+  if (!knownNames.includes(observerAgentName)) {
+    return {
+      enabled: false,
+      readiness: 'needs_setup',
+      source: result.source,
+      reason: `Unknown agent name '${observerAgentName}'`,
+      nextAction: `Use one of the known agent names: ${INTERNAL_AGENT_NAMES.join(', ')}`,
+      runtimeProfileId: null,
+      runtimeProfileType: null,
+      apiKeyEnv: null,
+      apiKeyPresent: false,
+      provider: null,
+      model: null,
+      timeoutMs: null,
+      baseUrl: null,
+    };
+  }
+  const agentKey = observerAgentName as InternalAgentName;
+  const agentConfig = config.internalAgents.agents[agentKey];
+
+  // Feature flag on but agent.enabled=false → disabled (not enabled)
+  if (!agentConfig || !agentConfig.enabled) {
+    return {
+      enabled: false,
+      readiness: 'disabled',
+      source: result.source,
+      reason: `${observerFlagId} feature flag is enabled but internalAgents.agents.${observerAgentName}.enabled is false`,
+      nextAction: `Set internalAgents.agents.${observerAgentName}.enabled=true in .pd/config.yaml, or disable features.${observerFlagId}`,
+      runtimeProfileId: null,
+      runtimeProfileType: null,
+      apiKeyEnv: null,
+      apiKeyPresent: false,
+      provider: null,
+      model: null,
+      timeoutMs: null,
+      baseUrl: null,
+    };
+  }
+
+  // 3) Find the agent's runtime profile
+  const runtimeProfileId = agentConfig.runtimeProfile ?? config.internalAgents.defaultRuntime;
+  const profile = config.runtimeProfiles[runtimeProfileId];
+
+  if (!profile) {
+    return {
+      enabled: true,
+      readiness: 'needs_setup',
+      source: result.source,
+      reason: `Runtime profile '${runtimeProfileId}' not found in .pd/config.yaml`,
+      nextAction: `Add runtime profile '${runtimeProfileId}' to .pd/config.yaml runtimeProfiles`,
+      runtimeProfileId,
+      runtimeProfileType: null,
+      apiKeyEnv: null,
+      apiKeyPresent: false,
+      provider: null,
+      model: null,
+      timeoutMs: null,
+      baseUrl: null,
+    };
+  }
+
+  // 4) For pi-ai profiles, check API key
+  if (profile.type === 'pi-ai') {
+    const apiKeyEnv = profile.apiKeyEnv ?? null;
+    const apiKeyPresent = !!apiKeyEnv && Object.prototype.hasOwnProperty.call(process.env, apiKeyEnv) && !!process.env[apiKeyEnv];
+
+    if (!apiKeyEnv) {
+      return {
+        enabled: true,
+        readiness: 'needs_setup',
+        source: result.source,
+        reason: `pi-ai profile '${runtimeProfileId}' missing apiKeyEnv`,
+        nextAction: `Add apiKeyEnv to runtime profile '${runtimeProfileId}' in .pd/config.yaml`,
+        runtimeProfileId,
+        runtimeProfileType: profile.type,
+        apiKeyEnv: null,
+        apiKeyPresent: false,
+        provider: profile.provider ?? null,
+        model: profile.model ?? null,
+        timeoutMs: profile.timeoutMs ?? null,
+        baseUrl: profile.baseUrl ?? null,
+      };
+    }
+
+    if (!apiKeyPresent) {
+      return {
+        enabled: true,
+        readiness: 'needs_setup',
+        source: result.source,
+        reason: `Environment variable '${apiKeyEnv}' is not set or empty`,
+        nextAction: `Set the environment variable '${apiKeyEnv}' with a valid API key`,
+        runtimeProfileId,
+        runtimeProfileType: profile.type,
+        apiKeyEnv,
+        apiKeyPresent: false,
+        provider: profile.provider ?? null,
+        model: profile.model ?? null,
+        timeoutMs: profile.timeoutMs ?? null,
+        baseUrl: profile.baseUrl ?? null,
+      };
+    }
+
+    // pi-ai with key present — runtime availability unknown without actual probe
+    return {
+      enabled: true,
+      readiness: 'not_ready',
+      source: result.source,
+      reason: `pi-ai profile configured with apiKeyEnv='${apiKeyEnv}' (key present); runtime availability unknown`,
+      nextAction: 'Run pd runtime probe to verify end-to-end connectivity',
+      runtimeProfileId,
+      runtimeProfileType: profile.type,
+      apiKeyEnv,
+      apiKeyPresent: true,
+      provider: profile.provider ?? null,
+      model: profile.model ?? null,
+      timeoutMs: profile.timeoutMs ?? null,
+      baseUrl: profile.baseUrl ?? null,
+    };
+  }
+
+  // 5) OpenClaw profile — CorrectionObserver does NOT support OpenClaw runtime
+  //    Mark as needs_setup with nextAction to configure a pi-ai profile
+  return {
+    enabled: true,
+    readiness: 'needs_setup',
+    source: result.source,
+    reason: `OpenClaw profile '${runtimeProfileId}' is not supported for observer runtime. Observers require a pi-ai profile with an API key.`,
+    nextAction: `Configure a pi-ai runtime profile for ${observerAgentName} in .pd/config.yaml (e.g., add a pi-ai profile with provider, model, and apiKeyEnv)`,
+    runtimeProfileId,
+    runtimeProfileType: profile.type,
+    apiKeyEnv: null,
+    apiKeyPresent: false,
+    provider: profile.provider ?? null,
+    model: profile.model ?? null,
+    timeoutMs: null,
+    baseUrl: null,
+  };
+}

package/src/core/runtime-v2-prompt-activation-reader.ts

@@ -1,8 +1,6 @@
-import * as path from 'path';
-import * as fs from 'fs';
-import * as yaml from 'js-yaml';
-import { SqliteConnection, SqliteActivationStateStore, computeEffectiveFlags, DEFAULT_FEATURE_FLAGS, filterPromptActivations, resolvePrincipleFromArtifact } from '@principles/core/runtime-v2';
-import type { EffectiveFeatureFlags, ActivatedPrinciple, PromptActivationReaderResult } from '@principles/core/runtime-v2';
+import { SqliteConnection, SqliteActivationStateStore, computeFeatureFlagsFromConfig, filterPromptActivations, resolvePrincipleFromArtifact } from '@principles/core/runtime-v2';
+import type { FeatureFlagsResult, ActivatedPrinciple, PromptActivationReaderResult } from '@principles/core/runtime-v2';
+import { loadPdConfigForPlugin } from './pd-config-loader.js';
 
 export { RUNTIME_V2_PRINCIPLE_BUDGET } from '@principles/core/runtime-v2';
 export type { ActivatedPrinciple, PromptActivationReaderResult };
@@ -11,12 +9,6 @@ export interface PromptActivationReaderDeps {
   logger?: { warn?: (msg: string) => void; info?: (msg: string) => void; error?: (msg: string) => void };
 }
 
-const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 export class PromptActivationReader {
   private readonly workspaceDir: string;
   private readonly deps: PromptActivationReaderDeps;
@@ -103,60 +95,20 @@ export class PromptActivationReader {
     }
   }
 
-  private loadFeatureFlags(): EffectiveFeatureFlags {
-    const configPath = path.join(this.workspaceDir, '.pd', 'feature-flags.yaml');
-
-    if (!fs.existsSync(configPath)) {
-      return computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-    }
-
-    let raw: string;
-    try {
-      raw = fs.readFileSync(configPath, 'utf8');
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      this.deps.logger?.warn?.(`[PD:RuntimeV2] Feature flags unreadable: ${msg} — using defaults`);
-      return computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-    }
-
-    let parsed: unknown;
-    try {
-      parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
-    } catch {
-      this.deps.logger?.warn?.(`[PD:RuntimeV2] Feature flags YAML parse error — using defaults`);
-      return {
-        ...computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath),
-        warnings: ['feature-flags.yaml: YAML parse error, using defaults'],
-      };
-    }
-
-    if (!isRecord(parsed)) {
-      this.deps.logger?.warn?.(`[PD:RuntimeV2] Feature flags not a mapping — using defaults`);
-      return {
-        ...computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath),
-        warnings: ['feature-flags.yaml: expected a mapping, using defaults'],
-      };
-    }
-
-    const parsedRecord: Record<string, unknown> = Object.create(null);
-    const yamlWarnings: string[] = [];
-    for (const key of Object.keys(parsed)) {
-      if (DANGEROUS_KEYS.has(key)) {
-        yamlWarnings.push(`feature-flags.yaml: dangerous key '${key}' rejected`);
-        continue;
-      }
-      if (Object.hasOwn(parsed, key)) {
-        parsedRecord[key] = parsed[key];
+  /**
+   * PRI-305/PRI-307: Load feature flags from .pd/config.yaml instead of .pd/feature-flags.yaml.
+   * Uses the shared plugin config loader for consistency.
+   */
+  private loadFeatureFlags(): FeatureFlagsResult {
+    const result = loadPdConfigForPlugin(this.workspaceDir);
+    const flags = computeFeatureFlagsFromConfig(result.effective);
+
+    if (!result.ok) {
+      for (const err of result.errors) {
+        this.deps.logger?.warn?.(`[PD:RuntimeV2] Config error at ${err.path}: ${err.reason}`);
       }
     }
 
-    const result = computeEffectiveFlags(parsedRecord, DEFAULT_FEATURE_FLAGS, configPath);
-    if (yamlWarnings.length > 0) {
-      result.warnings = [...yamlWarnings, ...result.warnings];
-      for (const w of yamlWarnings) {
-        this.deps.logger?.warn?.(`[PD:RuntimeV2] ${w}`);
-      }
-    }
-    return result;
+    return flags;
   }
 }

package/src/hooks/pain.ts

@@ -14,6 +14,7 @@ import { resolveWorkspaceDirForRuntimeV2 } from '../utils/workspace-resolver.js'
 import { PainToPrincipleService, PrincipleTreeLedgerAdapter, type PainDetectedData, type PainEvidenceEntry, MAX_EVIDENCE_ENTRIES, MAX_EVIDENCE_NOTE_CHARS } from '@principles/core/runtime-v2';
 import { evaluatePainDiagnosticGate } from '../core/pain-diagnostic-gate.js';
 import { sanitizeAssistantText } from './message-sanitize.js';
+import { loadPdConfigForPlugin } from '../core/pd-config-loader.js';
 
 /**
  * Interface for tool parameters to avoid 'any'
@@ -34,12 +35,17 @@ const WRITE_TOOLS = ['write', 'edit', 'apply_patch', 'write_file', 'edit_file',
 
 function createPainToPrincipleService(wctx: WorkspaceContext): PainToPrincipleService {
   const ledgerAdapter = new PrincipleTreeLedgerAdapter({ stateDir: wctx.stateDir });
+  // PRI-306: Load .pd/config.yaml and pass effectiveConfig to PainToPrincipleService
+  // so createPainSignalBridge uses config-driven runtime binding resolution.
+  const configResult = loadPdConfigForPlugin(wctx.workspaceDir);
   return new PainToPrincipleService({
     workspaceDir: wctx.workspaceDir,
     stateDir: wctx.stateDir,
     ledgerAdapter,
     owner: 'openclaw-plugin',
     autoIntakeEnabled: true,
+    effectiveConfig: configResult.effective,
+    getEnvVar: (name: string) => process.env[name],
   });
 }
 

package/src/index.ts

@@ -18,9 +18,7 @@ import type {
   PluginHookSubagentContext,
 } from './openclaw-sdk.js';
 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 { loadFeatureFlagFromConfig } from './core/pd-config-loader.js';
 import { classifyTask } from './core/local-worker-routing.js';
 import { completeShadowObservation, recordShadowRouting } from './core/shadow-observation-registry.js';
 import { getCommandDescription } from './i18n/commands.js';
@@ -75,66 +73,20 @@ const pendingShadowObservations = new Map<string, string>();
 // ── 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: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+/**
+ * PRI-305/PRI-307: Load feature flag from .pd/config.yaml instead of .pd/feature-flags.yaml.
+ * Delegates to the shared plugin config loader for consistency.
+ */
 function loadFeatureFlagFromWorkspace(
   workspaceDir: string,
   flagId: string,
   logger?: { warn?: (msg: string) => void; info?: (msg: string) => void },
 ): { enabled: boolean; source: string } {
-  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: string;
-  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: unknown;
-  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: Record<string, unknown> = 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 };
+  return loadFeatureFlagFromConfig(workspaceDir, flagId, logger);
 }
 
 // ── Evolution Worker Startup Gate (shared between index.ts and tests) ───────
@@ -157,7 +109,7 @@ export function shouldStartEvolutionWorker(
   }
   const disabledInfo = JSON.stringify({
     reason: 'mvp_quiet_per_adr0014',
-    nextAction: 'set evolution_worker.enabled=true in .pd/feature-flags.yaml to enable',
+    nextAction: 'set features.evolution_worker.enabled=true in .pd/config.yaml to enable',
     featureFlag: 'evolution_worker',
     boundedContext: 'legacy_evolution_worker',
     flagSource: flag.source,
@@ -181,7 +133,7 @@ export function shouldStartCorrectionObserver(
   }
   const disabledInfo = JSON.stringify({
     reason: 'correction_observer_disabled',
-    nextAction: 'set correction_observer.enabled=true in .pd/feature-flags.yaml to enable',
+    nextAction: 'set features.correction_observer.enabled=true in .pd/config.yaml to enable',
     featureFlag: 'correction_observer',
     boundedContext: 'correction_observer_service',
     flagSource: flag.source,