principles-disciple 1.45.0 → 1.47.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.45.0",
+  "version": "1.47.0",
   "skills": [
     "./skills"
   ],
@@ -76,8 +76,8 @@
     }
   },
   "buildFingerprint": {
-    "gitSha": "cab0dbd8e6e7",
-    "bundleMd5": "1505a7119addd2ee24059f2473cdb1ca",
-    "builtAt": "2026-04-14T10:58:07.896Z"
+    "gitSha": "70500e1475ef",
+    "bundleMd5": "607cfbcb4534d2cfdc45cb0cd019cd0b",
+    "builtAt": "2026-04-16T03:41:17.317Z"
   }
 }

package/package.json

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

package/src/core/evolution-reducer.ts

@@ -21,9 +21,23 @@ import type {
   PrincipleSuggestedRule,
 } from './evolution-types.js';
 import { isCompleteDetectorMetadata } from './evolution-types.js';
-import { updateTrainingStore } from './principle-tree-ledger.js';
+import { updateTrainingStore, addPrincipleToLedger, updatePrinciple, type LedgerPrinciple } from './principle-tree-ledger.js';
+import { PrincipleCompiler } from './principle-compiler/index.js';
+
+/**
+ * Wrapper for updatePrinciple calls in the compilation retry path.
+ * If updatePrinciple throws, logs the error instead of propagating —
+ * compilation retry state is best-effort and should not crash principle creation.
+ */
+function updateRetryCount(stateDir: string, workspaceDir: string, principleId: string, count: number): void {
+  try {
+    updatePrinciple(stateDir, principleId, { compilationRetryCount: count });
+  } catch (err) {
+    SystemLogger.log(workspaceDir, 'RETRY_COUNT_UPDATE_FAILED',
+      `Failed to update compilationRetryCount for ${principleId}: ${String(err)}`);
+  }
+}
 
- 
 export interface EvolutionReducer {
 
   emit(_event: EvolutionLoopEvent): void;
@@ -381,6 +395,80 @@ export class EvolutionReducerImpl implements EvolutionReducer {
       SystemLogger.log(this.workspaceDir, 'PRINCIPLE_SYNC_WARN', `Principle ${principleId} created in memory but failed to sync to PRINCIPLES.md — manual file check required`);
     }
 
+    // Add to ledger tree so the compiler can find this principle.
+    // Without this, newly diagnosed principles are invisible to the compiler
+    // (which reads tree.principles, not trainingStore or PRINCIPLES.md).
+    if (this.stateDir) {
+      try {
+        // Build a LedgerPrinciple (tree schema) from the evolution-types Principle.
+        // Tree schema Principle does NOT have: source, guardrails, contextTags, validation,
+        // feedbackScore, usageCount, activatedAt, abstractedPrinciple, valueMetrics.
+        // Pain source info is stored via derivedFromPainIds (which the compiler uses).
+        const ledgerPrinciple: LedgerPrinciple = {
+          id: principle.id,
+          version: principle.version,
+          text: principle.text,
+          triggerPattern: principle.trigger,
+          action: principle.action,
+          status: principle.status,
+          evaluability: principle.evaluability,
+          coreAxiomId: principle.coreAxiomId,
+          priority: principle.priority ?? 'P1',
+          scope: principle.scope ?? 'general',
+          domain: principle.domain,
+          suggestedRules: principle.suggestedRules?.map((r) => r.name),
+          detectorMetadata: principle.detectorMetadata,
+          deprecatedAt: principle.deprecatedAt,
+          deprecatedReason: undefined,
+          createdAt: principle.createdAt,
+          updatedAt: now,
+          // Ledger-only fields (derived from evolution-types Principle where applicable):
+          valueScore: 0,
+          adherenceRate: 0,
+          painPreventedCount: 0,
+          lastPainPreventedAt: undefined,
+          derivedFromPainIds: [params.painId],
+          ruleIds: [],
+          conflictsWithPrincipleIds: [],
+          supersedesPrincipleId: undefined,
+        };
+        addPrincipleToLedger(this.stateDir, ledgerPrinciple);
+        SystemLogger.log(this.workspaceDir, 'LEDGER_PRINCIPLE_ADDED', `Principle ${principleId} added to ledger tree`);
+
+        // Sync compile: attempt to compile immediately unless evaluability is manual_only.
+        // Failures are not fatal — heartbeat backfill will retry automatically.
+        if (evaluability !== 'manual_only' && this.stateDir) {
+          const trajectory = TrajectoryRegistry.get(this.workspaceDir);
+          const compiler = new PrincipleCompiler(this.stateDir, trajectory);
+          try {
+            const result = compiler.compileOne(principleId);
+            if (result.success) {
+              // Reset retry count on success
+              updatePrinciple(this.stateDir, principleId, { compilationRetryCount: undefined });
+              SystemLogger.log(this.workspaceDir, 'COMPILE_SUCCESS', `Principle ${principleId} compiled successfully`);
+            } else {
+              // Compile returned failure — queue for backfill retry (count=0 means "queued", Phase 2 will pick it up).
+              // This gives exactly 5 total attempts before exhaustion (backfill: 0-4, sync: 0-4).
+              updateRetryCount(this.stateDir, this.workspaceDir, principleId, 0);
+              SystemLogger.log(
+                this.workspaceDir, 'COMPILE_FAILED',
+                `Principle ${principleId} compile failed: ${result.reason ?? 'unknown'} (attempt 1/5)`
+              );
+            }
+          } catch (compileErr) {
+            // Unexpected error during compilation — queue for backfill retry
+            updateRetryCount(this.stateDir, this.workspaceDir, principleId, 0);
+            SystemLogger.log(
+              this.workspaceDir, 'COMPILE_FAILED',
+              `Principle ${principleId} compile threw: ${String(compileErr)} (attempt 1/5)`
+            );
+          }
+        }
+      } catch (err) {
+        SystemLogger.log(this.workspaceDir, 'LEDGER_PRINCIPLE_ADD_FAILED', `Failed to add ${principleId} to ledger tree: ${String(err)}`);
+      }
+    }
+
     // #204: Write to training store so listEvaluablePrinciples() can find this principle
     if (this.stateDir) {
       try {

package/src/core/pain.ts

@@ -32,9 +32,11 @@ export interface PainFlagData {
   /** Whether this involves risky operation ('true' / 'false') */
   is_risky: string;
   /** Correlation trace ID (for linking events across the pipeline) */
-  trace_id?: string;
-  /** Short preview of text that triggered this pain signal */
-  trigger_text_preview?: string;
+  trace_id: string;
+  /** Preview of the text that triggered this pain */
+  trigger_text_preview: string;
+  /** Trajectory pain_events row ID (set by recordPainEvent) */
+  pain_event_id?: string;
 }
 
 export interface PainFlagContractResult {
@@ -65,6 +67,7 @@ export function buildPainFlag(input: {
   is_risky?: boolean;
   trace_id?: string;
   trigger_text_preview?: string;
+  pain_event_id?: string;
 }): PainFlagData {
   // Omit optional fields when not provided — prevents writing empty lines to disk
   // which causes agent confusion (SKILL.md vs reality drift)
@@ -78,6 +81,7 @@ export function buildPainFlag(input: {
     is_risky: input.is_risky ? 'true' : 'false',
     trace_id: input.trace_id ?? '',
     trigger_text_preview: input.trigger_text_preview ?? '',
+    pain_event_id: input.pain_event_id,
   };
 }
 

package/src/core/principle-tree-ledger.ts

@@ -368,7 +368,7 @@ export async function saveLedgerAsync(stateDir: string, store: HybridLedgerStore
 
 export function updateTrainingStore(
   stateDir: string,
-   
+
   mutate: (store: LegacyPrincipleTrainingStore) => void,
 ): void {
   mutateLedger(stateDir, (store) => {
@@ -376,6 +376,24 @@ export function updateTrainingStore(
   });
 }
 
+/**
+ * Add a new principle directly to the ledger tree.
+ * This is the companion to updatePrinciple() — use this when creating a NEW
+ * principle so the compiler can find it in tree.principles.
+ *
+ * Idempotent: if the principle already exists, overwrites (update semantics).
+ */
+export function addPrincipleToLedger(
+  stateDir: string,
+  principle: LedgerPrinciple,
+): LedgerPrinciple {
+  return mutateLedger(stateDir, (store) => {
+    store.tree.principles[principle.id] = principle;
+    store.tree.lastUpdated = new Date().toISOString();
+    return principle;
+  });
+}
+
 export function createRule(stateDir: string, rule: LedgerRule): LedgerRule {
   return mutateLedger(stateDir, (store) => {
     const principle = store.tree.principles[rule.principleId];

package/src/core/trajectory.ts

@@ -237,10 +237,11 @@ export class TrajectoryDatabase {
     return rowId;
   }
 
-  recordPainEvent(input: TrajectoryPainEventInput): void {
+  recordPainEvent(input: TrajectoryPainEventInput): number {
     this.recordSession({ sessionId: input.sessionId, startedAt: input.createdAt });
+    let insertedId = -1;
     this.withWrite(() => {
-      this.db.prepare(`
+      const runResult = this.db.prepare(`
         INSERT INTO pain_events (
           session_id, source, score, reason, severity, origin, confidence, text, created_at
         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
@@ -255,15 +256,22 @@ export class TrajectoryDatabase {
         input.text ?? null,
         input.createdAt ?? nowIso(),
       );
-
-      // Maintain FTS5 index: insert text into pain_events_fts if text is provided (MEM-03, MEM-04)
-      if (input.text) {
-        const lastId = this.db.prepare('SELECT last_insert_rowid() as id').get() as { id: number };
+      insertedId = runResult.lastInsertRowid as number;
+    });
+    // FTS indexing is best-effort — run outside the transaction so it cannot
+    // roll back the committed pain event row (MEM-03, MEM-04).
+    if (input.text && insertedId > 0) {
+      try {
         this.db.prepare(`
           INSERT INTO pain_events_fts (text, pain_event_id) VALUES (?, ?)
-        `).run(input.text, lastId.id);
+        `).run(input.text, insertedId);
+      } catch (err) {
+        // Non-fatal: FTS index is for search convenience, not correctness.
+        // Log but do not re-throw — the pain event itself is already committed.
+        console.warn(`[trajectory] FTS index insert failed for pain_event ${insertedId}: ${String(err)}`);
       }
-    });
+    }
+    return insertedId;
   }
 
   /**

package/src/hooks/pain.ts

@@ -295,6 +295,19 @@ export function handleAfterToolCall(
   const painScore = computePainScore(1, false, false, isRisk ? 20 : 0, effectiveWorkspaceDir);
   const traceId = createTraceId();
 
+  // Record to trajectory FIRST so we get the real auto-increment ID.
+  // This ID propagates through the pain flag → evolution task → principle,
+  // so the compiler can later resolve derivedFromPainIds correctly.
+  const trajectoryPainId = wctx.trajectory?.recordPainEvent({
+    sessionId,
+    source: 'tool_failure',
+    score: painScore,
+    reason: `Tool ${event.toolName} failed on ${relPath}`,
+    severity: painScore >= 70 ? 'severe' : painScore >= 40 ? 'moderate' : 'mild',
+    origin: 'system_infer',
+    text: params.text ?? params.content ?? undefined,
+  });
+
   const painData = buildPainFlag({
     source: 'tool_failure',
     score: String(painScore),
@@ -303,6 +316,7 @@ export function handleAfterToolCall(
     trace_id: traceId,
     session_id: sessionId,
     agent_id: ctx.agentId || '',
+    pain_event_id: trajectoryPainId !== undefined && trajectoryPainId >= 0 ? String(trajectoryPainId) : undefined,
   });
 
   try {
@@ -355,15 +369,6 @@ export function handleAfterToolCall(
     reason: `Tool ${event.toolName} failed on ${relPath}`,
     isRisky: isRisk,
   });
-    wctx.trajectory?.recordPainEvent?.({
-      sessionId,
-      source: 'tool_failure',
-      score: painScore,
-      reason: `Tool ${event.toolName} failed on ${relPath}`,
-      severity: painScore >= 70 ? 'severe' : painScore >= 40 ? 'moderate' : 'mild',
-      origin: 'system_infer',
-      text: params.text ?? params.content ?? undefined,  // Store original text/content that failed
-    });
 
   // Log to EvolutionLogger
   const evoLogger = getEvolutionLogger(effectiveWorkspaceDir, wctx.trajectory);

package/src/service/evolution-worker.ts

@@ -15,6 +15,7 @@ import { initPersistence, flushAllSessions } from '../core/session-tracker.js';
 import { addDiagnosticianTask, completeDiagnosticianTask } from '../core/diagnostician-task-store.js';
 import { getEvolutionLogger } from '../core/evolution-logger.js';
 import type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
+import type { PrincipleEvaluability } from '../types/principle-tree-schema.js';
 export type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
 import { atomicWriteFileSync } from '../utils/io.js';
 
@@ -37,6 +38,8 @@ import {
     type NocturnalSessionSnapshot,
 } from '../core/nocturnal-trajectory-extractor.js';
 import { validateNocturnalSnapshotIngress } from '../core/nocturnal-snapshot-contract.js';
+import { PrincipleCompiler } from '../core/principle-compiler/index.js';
+import { loadLedger, updatePrinciple } from '../core/principle-tree-ledger.js';
 import { isExpectedSubagentError } from './subagent-workflow/subagent-error-utils.js';
 import { readPainFlagContract } from '../core/pain.js';
 import { CorrectionObserverWorkflowManager, correctionObserverWorkflowSpec } from './subagent-workflow/correction-observer-workflow-manager.js';
@@ -141,6 +144,9 @@ export interface EvolutionQueueItem {
     // Attaches explicit recent pain signal without merging task kinds.
     // Used by target selector for ranking bias and context enrichment.
     recentPainContext?: RecentPainContext;
+
+    /** Trajectory pain_events row ID — set when pain flag includes pain_event_id */
+    painEventId?: number;
 }
 
 // ── Queue Migration (extracted to queue-migration.ts) ────────────────────────
@@ -305,6 +311,7 @@ export function hasEquivalentPromotedRule(dictionary: { getAllRules(): Record<st
 interface ParsedPainValues {
     score: number; source: string; reason: string; preview: string;
     traceId: string; sessionId: string; agentId: string;
+    painEventId?: number;
 }
 
  
@@ -352,6 +359,7 @@ async function doEnqueuePainTask(
             status: 'pending', session_id: v.sessionId || undefined,
             agent_id: v.agentId || undefined, traceId: effectiveTraceId,
             retryCount: 0, maxRetries: 3,
+            painEventId: v.painEventId,
         });
 
         saveEvolutionQueue(queuePath, queue);
@@ -400,6 +408,8 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
             const traceId = contract.data.trace_id ?? '';
             const sessionId = contract.data.session_id ?? '';
             const agentId = contract.data.agent_id ?? '';
+            const painEventIdRaw = contract.data.pain_event_id;
+            const painEventId = painEventIdRaw ? parseInt(painEventIdRaw, 10) : undefined;
 
             result.exists = true;
             result.score = score;
@@ -414,7 +424,7 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
 
             if (logger) logger.info(`[PD:EvolutionWorker] Detected pain flag (score: ${score}, source: ${source}). Enqueueing evolution task.`);
             return doEnqueuePainTask(wctx, logger, painFlagPath, result, {
-                score, source, reason, preview, traceId, sessionId, agentId,
+                score, source, reason, preview, traceId, sessionId, agentId, painEventId,
             });
         }
 
@@ -470,6 +480,7 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
                     preview: jsonPreview, traceId: '',
                     sessionId: jsonPain.session_id || '',
                     agentId: jsonPain.agent_id || '',
+                    painEventId: jsonPain.pain_event_id ? parseInt(jsonPain.pain_event_id, 10) : undefined,
                 });
             }
         } catch { /* Not JSON — fall through to KV/Markdown parsing */ }
@@ -492,6 +503,7 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
         let traceId = '';
         let sessionId = '';
         let agentId = '';
+        let painEventId: number | undefined;
 
         for (const line of lines) {
             // KV format: "key: value"
@@ -503,6 +515,10 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
             if (line.startsWith('trace_id:')) traceId = line.split(':', 2)[1].trim();
             if (line.startsWith('session_id:')) sessionId = line.slice('session_id:'.length).trim();
             if (line.startsWith('agent_id:')) agentId = line.slice('agent_id:'.length).trim();
+            if (line.startsWith('pain_event_id:')) {
+                const raw = line.slice('pain_event_id:'.length).trim();
+                painEventId = parseInt(raw, 10) || undefined;
+            }
 
             // Key=Value fallback format: "key=value" (pain skill manual output)
             // Handles both uppercase (Source=X) and lowercase (source=x) variants
@@ -544,7 +560,7 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
 
         return doEnqueuePainTask(wctx, logger, painFlagPath, result, {
             score, source, reason, preview,
-            traceId, sessionId, agentId,
+            traceId, sessionId, agentId, painEventId,
         });
 
     } catch (err) {
@@ -554,8 +570,147 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
     return result;
 }
 
- 
- 
+/**
+ * Process compilation backfill and retry loop.
+ * Phase 1 — Backfill: on first call, scan for old principles (compilationRetryCount === undefined)
+ *            with evaluability !== 'manual_only' and no active implementation, queue them (set to 0).
+ * Phase 2 — Retry: compile all principles with compilationRetryCount >= 0.
+ * After 5 consecutive failures, downgrades to manual_only and logs COMPILE_EXHAUSTED.
+ */
+export async function processCompilationBackfill(
+    wctx: WorkspaceContext,
+    logger: PluginLogger,
+): Promise<void> {
+    if (!wctx.stateDir) return;
+
+    let ledger: ReturnType<typeof loadLedger>;
+    try {
+        ledger = loadLedger(wctx.stateDir);
+    } catch (err) {
+        logger?.warn?.(`[PD:EvolutionWorker] CompilationBackfill: failed to load ledger: ${String(err)}`);
+        return;
+    }
+
+    // ── Phase 1: Backfill old principles (runs once per process) ─────────────────
+    const backfillMarkerPath = path.join(wctx.stateDir, 'COMPILATION_BACKFILL_DONE');
+    const hasBackfillRun = fs.existsSync(backfillMarkerPath);
+    if (!hasBackfillRun) {
+        let backfillQueued = 0;
+        for (const [principleId, principle] of Object.entries(ledger.tree.principles)) {
+            if (principle.compilationRetryCount !== undefined) continue; // already processed
+            if (principle.evaluability === 'manual_only') continue;
+            // Check if already has active implementation
+            const hasActiveImpl = Object.values(ledger.tree.implementations).some(
+                (impl) => impl.lifecycleState === 'active' && (
+                    ledger.tree.rules[impl.ruleId]?.principleId === principleId
+                )
+            );
+            if (hasActiveImpl) {
+                // Already compiled — mark as done
+                updatePrinciple(wctx.stateDir, principleId, { compilationRetryCount: undefined });
+            } else {
+                // Needs compilation — queue it
+                updatePrinciple(wctx.stateDir, principleId, { compilationRetryCount: 0 });
+                backfillQueued++;
+            }
+        }
+        if (backfillQueued > 0) {
+            SystemLogger.log(wctx.workspaceDir, 'COMPILE_BACKFILL_QUEUED',
+                `Queued ${backfillQueued} old principles for compilation`);
+        }
+        // Write marker so we don't backfill again in this process
+        atomicWriteFileSync(backfillMarkerPath, new Date().toISOString());
+    }
+
+    // ── Phase 2: Retry pending compilations ───────────────────────────────────
+    const trajectory = TrajectoryRegistry.get(wctx.workspaceDir);
+    const compiler = new PrincipleCompiler(wctx.stateDir, trajectory);
+
+    // Re-load ledger after potential backfill updates
+    ledger = loadLedger(wctx.stateDir);
+
+    for (const [principleId, principle] of Object.entries(ledger.tree.principles)) {
+        const count = principle.compilationRetryCount;
+
+        // Skip: not in retry queue (undefined = done/succeeded)
+        if (count === undefined) continue;
+
+        // Skip: already exhausted (count >= 5 means 5 attempts already made)
+        if (count >= 5) continue;
+
+        // Error-isolate each principle so one failure doesn't stop all other retries
+        try {
+            const result = compiler.compileOne(principleId);
+            if (result.success) {
+                safeUpdateRetryCount(wctx.stateDir, wctx.workspaceDir, principleId, undefined);
+                SystemLogger.log(wctx.workspaceDir, 'COMPILE_SUCCESS',
+                    `Principle ${principleId} compiled successfully (attempt ${count + 1})`);
+            } else {
+                const nextCount = count + 1;
+                if (nextCount >= 5) {
+                    // Exhausted: single write to set manual_only (no intermediate count write)
+                    safeUpdatePrinciple(wctx.stateDir, wctx.workspaceDir, principleId, {
+                        evaluability: 'manual_only',
+                        compilationRetryCount: undefined,
+                    });
+                    SystemLogger.log(wctx.workspaceDir, 'COMPILE_EXHAUSTED',
+                        `Principle ${principleId} compilation exhausted after 5 attempts: ${result.reason ?? 'unknown'}`);
+                } else {
+                    safeUpdateRetryCount(wctx.stateDir, wctx.workspaceDir, principleId, nextCount);
+                    SystemLogger.log(wctx.workspaceDir, 'COMPILE_FAILED',
+                        `Principle ${principleId} compile failed: ${result.reason ?? 'unknown'} (attempt ${nextCount}/5)`);
+                }
+            }
+        } catch (compileErr) {
+            const nextCount = count + 1;
+            if (nextCount >= 5) {
+                // Exhausted: single write to set manual_only (no intermediate count write)
+                safeUpdatePrinciple(wctx.stateDir, wctx.workspaceDir, principleId, {
+                    evaluability: 'manual_only',
+                    compilationRetryCount: undefined,
+                });
+                SystemLogger.log(wctx.workspaceDir, 'COMPILE_EXHAUSTED',
+                    `Principle ${principleId} compilation exhausted after 5 attempts: threw ${String(compileErr)}`);
+            } else {
+                safeUpdateRetryCount(wctx.stateDir, wctx.workspaceDir, principleId, nextCount);
+                SystemLogger.log(wctx.workspaceDir, 'COMPILE_FAILED',
+                    `Principle ${principleId} compile threw: ${String(compileErr)} (attempt ${nextCount}/5)`);
+            }
+        }
+    }
+}
+
+/**
+ * Wrapper for updatePrinciple in the retry loop — logs but does not propagate errors.
+ * If update fails, the principle stays in its current retry state and will be
+ * picked up again on the next heartbeat.
+ */
+function safeUpdateRetryCount(stateDir: string, workspaceDir: string, principleId: string, count: number | undefined): void {
+    try {
+        updatePrinciple(stateDir, principleId, { compilationRetryCount: count });
+    } catch (err) {
+        SystemLogger.log(workspaceDir, 'RETRY_COUNT_UPDATE_FAILED',
+            `Failed to update retry count for ${principleId}: ${String(err)}`);
+    }
+}
+
+/**
+ * Wrapper for updatePrinciple with multiple fields — logs but does not propagate errors.
+ */
+function safeUpdatePrinciple(
+    stateDir: string,
+    workspaceDir: string,
+    principleId: string,
+    updates: { evaluability?: PrincipleEvaluability; compilationRetryCount?: number },
+): void {
+    try {
+        updatePrinciple(stateDir, principleId, updates);
+    } catch (err) {
+        SystemLogger.log(workspaceDir, 'RETRY_PRINCIPLE_UPDATE_FAILED',
+            `Failed to update principle ${principleId}: ${String(err)}`);
+    }
+}
+
 async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogger, eventLog: EventLog, api?: OpenClawPluginApi) {
     const queuePath = wctx.resolve('EVOLUTION_QUEUE');
     if (!fs.existsSync(queuePath)) {
@@ -1944,6 +2099,12 @@ export const EvolutionWorkerService: ExtendedEvolutionWorkerService = {
                 const mergedConfig = loadNocturnalConfigMerged(wctx.stateDir);
                 const { sleepReflection: sleepConfig, keywordOptimization: kwOptConfig } = mergedConfig;
 
+                // Compilation backfill: runs on every heartbeat to retry failed compilations.
+                // Fire-and-forget — errors are logged within the function.
+                processCompilationBackfill(wctx, logger).catch((err) => {
+                    logger?.error?.(`[PD:EvolutionWorker] CompilationBackfill threw: ${String(err)}`);
+                });
+
                 const idleResult = checkWorkspaceIdle(wctx.workspaceDir, {});
                 logger?.info?.(`[PD:EvolutionWorker] HEARTBEAT cycle=${new Date().toISOString()} idle=${idleResult.isIdle} idleForMs=${idleResult.idleForMs} userActiveSessions=${idleResult.userActiveSessions} abandonedSessions=${idleResult.abandonedSessionIds.length} lastActivityEpoch=${idleResult.mostRecentActivityAt} triggerMode=${sleepConfig.trigger_mode}`);
 

package/src/service/queue-io.ts

@@ -68,6 +68,8 @@ export interface RecentPainContext {
         reason: string;
         timestamp: string;
         sessionId: string;
+        /** Trajectory pain_events row ID — set when pain flag includes pain_event_id */
+        painEventId?: number;
     } | null;
     recentPainCount: number;
     recentMaxPainScore: number;
@@ -150,10 +152,12 @@ export function readRecentPainContext(wctx: WorkspaceContext): RecentPainContext
         const reason = contract.data.reason ?? '';
         const timestamp = contract.data.time ?? '';
         const sessionId = contract.data.session_id ?? '';
+        const painEventIdRaw = contract.data.pain_event_id;
+        const painEventId = painEventIdRaw ? parseInt(painEventIdRaw, 10) : undefined;
 
         if (score > 0) {
             return {
-                mostRecent: { score, source, reason, timestamp, sessionId },
+                mostRecent: { score, source, reason, timestamp, sessionId, painEventId },
                 recentPainCount: 1,
                 recentMaxPainScore: score,
             };

package/src/types/principle-tree-schema.ts

@@ -76,6 +76,10 @@ export interface Principle {
 
   // Detector metadata (for auto-training eligibility)
   detectorMetadata?: PrincipleDetectorSpec;
+
+  // Compilation retry tracking (for runtime auto-trigger)
+  // undefined = not yet attempted or succeeded; 0 = queued; n >= 1 = retry attempt n
+  compilationRetryCount?: number;
 }
 
 // =========================================================================

package/tests/core/evolution-reducer.compilation-retry.test.ts

@@ -0,0 +1,188 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { EvolutionReducerImpl } from '../../src/core/evolution-reducer.js';
+import { loadLedger } from '../../src/core/principle-tree-ledger.js';
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-evolution-compile-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+// Minimal state dir structure
+function makeStateDir(workspace: string): string {
+  const stateDir = path.join(workspace, '.state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'EVOLUTION_STREAM'), '', 'utf8');
+  fs.writeFileSync(path.join(stateDir, 'PRINCIPLES'), '', 'utf8');
+  fs.writeFileSync(path.join(stateDir, 'evolution_queue.json'), '[]', 'utf8');
+  fs.writeFileSync(path.join(stateDir, 'ledger.json'), JSON.stringify({
+    trainingStore: {},
+    tree: { principles: {}, rules: {}, implementations: {}, metrics: {}, lastUpdated: new Date().toISOString() },
+  }), 'utf8');
+  return stateDir;
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// createPrincipleFromDiagnosis — compilationRetryCount initialization
+// ---------------------------------------------------------------------------
+
+describe('createPrincipleFromDiagnosis — compilationRetryCount initialization', () => {
+  it('sets compilationRetryCount=0 when evaluability is weak_heuristic (queued for compilation)', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+    const reducer = new EvolutionReducerImpl({ workspaceDir: workspace, stateDir });
+
+    const id = reducer.createPrincipleFromDiagnosis({
+      painId: `pain-weak-heuristic-${Date.now()}`,
+      painType: 'tool_failure',
+      triggerPattern: 'bash rm fails',
+      action: 'verify file exists before rm',
+      source: 'test-compilation-retry',
+      evaluability: 'weak_heuristic',
+    });
+
+    expect(id).not.toBeNull();
+    const ledger = loadLedger(stateDir);
+    const principle = ledger.tree.principles[id as string];
+    expect(principle).toBeDefined();
+    // Compilation queued: count >= 0 means queued
+    expect(typeof principle?.compilationRetryCount).toBe('number');
+    expect(principle?.compilationRetryCount).toBeGreaterThanOrEqual(0);
+  });
+
+  it('sets compilationRetryCount=0 when evaluability is deterministic', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+    const reducer = new EvolutionReducerImpl({ workspaceDir: workspace, stateDir });
+
+    const id = reducer.createPrincipleFromDiagnosis({
+      painId: `pain-deterministic-${Date.now()}`,
+      painType: 'tool_failure',
+      triggerPattern: 'edit without read',
+      action: 'always read before edit',
+      source: 'test-compilation-retry',
+      evaluability: 'deterministic',
+    });
+
+    expect(id).not.toBeNull();
+    const ledger = loadLedger(stateDir);
+    const principle = ledger.tree.principles[id as string];
+    expect(principle).toBeDefined();
+    expect(typeof principle?.compilationRetryCount).toBe('number');
+    expect(principle?.compilationRetryCount).toBeGreaterThanOrEqual(0);
+  });
+
+  it('does NOT set compilationRetryCount when evaluability is manual_only', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+    const reducer = new EvolutionReducerImpl({ workspaceDir: workspace, stateDir });
+
+    const id = reducer.createPrincipleFromDiagnosis({
+      painId: `pain-manual-only-${Date.now()}`,
+      painType: 'tool_failure',
+      triggerPattern: 'generic pain',
+      action: 'be more careful',
+      source: 'test-compilation-retry',
+      evaluability: 'manual_only',
+    });
+
+    expect(id).not.toBeNull();
+    const ledger = loadLedger(stateDir);
+    const principle = ledger.tree.principles[id as string];
+    expect(principle).toBeDefined();
+    // manual_only principles should NOT be queued for compilation
+    expect(principle?.compilationRetryCount).toBeUndefined();
+    expect(principle?.evaluability).toBe('manual_only');
+  });
+
+  it('defaults to weak_heuristic and queues for compilation when no evaluability provided', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+    const reducer = new EvolutionReducerImpl({ workspaceDir: workspace, stateDir });
+
+    const id = reducer.createPrincipleFromDiagnosis({
+      painId: `pain-default-${Date.now()}`,
+      painType: 'tool_failure',
+      triggerPattern: 'some pattern',
+      action: 'some action',
+      source: 'test-compilation-retry',
+    });
+
+    expect(id).not.toBeNull();
+    const ledger = loadLedger(stateDir);
+    const principle = ledger.tree.principles[id as string];
+    expect(principle).toBeDefined();
+    // default evaluability is weak_heuristic, which should queue for compilation
+    expect(typeof principle?.compilationRetryCount).toBe('number');
+    expect(principle?.compilationRetryCount).toBeGreaterThanOrEqual(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createPrincipleFromDiagnosis — compilationRetryCount increments on compile failure
+// ---------------------------------------------------------------------------
+
+describe('createPrincipleFromDiagnosis — compilationRetryCount increments on failure', () => {
+  it('increments to 1 when compilation fails (no trajectory data)', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+    const reducer = new EvolutionReducerImpl({ workspaceDir: workspace, stateDir });
+
+    const id = reducer.createPrincipleFromDiagnosis({
+      painId: `pain-fail-${Date.now()}`,
+      painType: 'tool_failure',
+      triggerPattern: 'unknown tool',
+      action: 'do nothing',
+      source: 'test-compilation-retry',
+      evaluability: 'weak_heuristic',
+    });
+
+    expect(id).not.toBeNull();
+    const ledger = loadLedger(stateDir);
+    const principle = ledger.tree.principles[id as string];
+    expect(principle).toBeDefined();
+    // Compilation was attempted and failed (no trajectory data) → count should be 0
+    // (sync failure sets count=0 so Phase 2 gets exactly 5 total attempts)
+    expect(principle?.compilationRetryCount).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Principle schema — compilationRetryCount field exists and persists
+// ---------------------------------------------------------------------------
+
+describe('Principle schema — compilationRetryCount field persists', () => {
+  it('compilationRetryCount is stored and retrieved correctly', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+    const reducer = new EvolutionReducerImpl({ workspaceDir: workspace, stateDir });
+
+    const id = reducer.createPrincipleFromDiagnosis({
+      painId: `pain-schema-${Date.now()}`,
+      painType: 'tool_failure',
+      triggerPattern: 'test pattern',
+      action: 'test action',
+      source: 'test-compilation-retry',
+      evaluability: 'weak_heuristic',
+    });
+
+    expect(id).not.toBeNull();
+    // Reload ledger to verify persistence
+    const ledger = loadLedger(stateDir);
+    const principle = ledger.tree.principles[id as string];
+    expect(principle).toBeDefined();
+    expect(typeof principle?.compilationRetryCount).toBe('number');
+    expect(principle?.compilationRetryCount).toBeGreaterThanOrEqual(0);
+  });
+});

package/tests/service/evolution-worker.compilation-backfill.test.ts

@@ -0,0 +1,199 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { addPrincipleToLedger, loadLedger, type LedgerPrinciple } from '../../src/core/principle-tree-ledger.js';
+import type { WorkspaceContext } from '../../src/core/workspace-context.js';
+import type { PluginLogger } from '../../src/openclaw-sdk.js';
+import { processCompilationBackfill } from '../../src/service/evolution-worker.js';
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-backfill-test-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function makeStateDir(workspace: string): string {
+  const stateDir = path.join(workspace, '.state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(path.join(stateDir, 'EVOLUTION_STREAM'), '', 'utf8');
+  fs.writeFileSync(path.join(stateDir, 'PRINCIPLES'), '', 'utf8');
+  fs.writeFileSync(path.join(stateDir, 'evolution_queue.json'), '[]', 'utf8');
+  fs.writeFileSync(path.join(stateDir, 'ledger.json'), JSON.stringify({
+    trainingStore: {},
+    tree: { principles: {}, rules: {}, implementations: {}, metrics: {}, lastUpdated: new Date().toISOString() },
+  }), 'utf8');
+  return stateDir;
+}
+
+function makeWctx(workspace: string, stateDir: string): WorkspaceContext {
+  return {
+    workspaceDir: workspace,
+    stateDir,
+    resolve: (file: string) => path.join(stateDir, file),
+  } as unknown as WorkspaceContext;
+}
+
+function makePrinciple(id: string, overrides: Partial<LedgerPrinciple> = {}): LedgerPrinciple {
+  return {
+    id,
+    version: 1,
+    text: `principle ${id}`,
+    triggerPattern: 'test',
+    action: 'test action',
+    status: 'active',
+    priority: 'P1',
+    scope: 'general',
+    evaluability: 'weak_heuristic',
+    compilationRetryCount: undefined,
+    ruleIds: [],
+    conflictsWithPrincipleIds: [],
+    derivedFromPainIds: [],
+    valueScore: 0,
+    adherenceRate: 0,
+    painPreventedCount: 0,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    ...overrides,
+  } as LedgerPrinciple;
+}
+
+const noopLogger: PluginLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Phase 1: Backfill
+// ---------------------------------------------------------------------------
+
+describe('processCompilationBackfill — Phase 1 backfill', () => {
+  it('sets compilationRetryCount=0 for old principles without retry count', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+
+    addPrincipleToLedger(stateDir, makePrinciple('P_001', {
+      evaluability: 'weak_heuristic',
+      compilationRetryCount: undefined,
+    }));
+
+    const wctx = makeWctx(workspace, stateDir);
+    processCompilationBackfill(wctx, noopLogger);
+
+    const ledger = loadLedger(stateDir);
+    // Phase 1 sets count=0, then Phase 2 runs and increments to 1 (compilation fails without trajectory data)
+    // The key assertion: count was set to 0 at some point (proves backfill ran)
+    expect(ledger.tree.principles['P_001'].compilationRetryCount).toBeGreaterThanOrEqual(0);
+  });
+
+  it('skips principles with manual_only evaluability', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+
+    addPrincipleToLedger(stateDir, makePrinciple('P_002', {
+      evaluability: 'manual_only',
+      compilationRetryCount: undefined,
+    }));
+
+    const wctx = makeWctx(workspace, stateDir);
+    processCompilationBackfill(wctx, noopLogger);
+
+    const ledger = loadLedger(stateDir);
+    expect(ledger.tree.principles['P_002'].compilationRetryCount).toBeUndefined();
+  });
+
+  it('writes COMPILATION_BACKFILL_DONE marker after backfill', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+
+    addPrincipleToLedger(stateDir, makePrinciple('P_003', {
+      evaluability: 'weak_heuristic',
+      compilationRetryCount: undefined,
+    }));
+
+    const wctx = makeWctx(workspace, stateDir);
+    processCompilationBackfill(wctx, noopLogger);
+
+    const markerPath = path.join(stateDir, 'COMPILATION_BACKFILL_DONE');
+    expect(fs.existsSync(markerPath)).toBe(true);
+  });
+
+  it('does not re-backfill if marker already exists', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+
+    // Pre-write the marker so Phase 1 (backfill) is skipped
+    const markerPath = path.join(stateDir, 'COMPILATION_BACKFILL_DONE');
+    fs.writeFileSync(markerPath, new Date().toISOString(), 'utf8');
+
+    // Add principle with compilationRetryCount already set to a high value
+    // (simulating already-processed-by-Phase2)
+    addPrincipleToLedger(stateDir, makePrinciple('P_004', {
+      evaluability: 'weak_heuristic',
+      compilationRetryCount: 2,
+    }));
+
+    const wctx = makeWctx(workspace, stateDir);
+    processCompilationBackfill(wctx, noopLogger);
+
+    const ledger = loadLedger(stateDir);
+    // Phase 1 was skipped (marker exists), but Phase 2 still ran and incremented count
+    // So count goes from 2 -> 3 (compilation fails without trajectory data)
+    expect(ledger.tree.principles['P_004'].compilationRetryCount).toBe(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Phase 2: Retry loop
+// ---------------------------------------------------------------------------
+
+describe('processCompilationBackfill — Phase 2 retry loop', () => {
+  it('increments count on compile failure (below exhaustion)', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+
+    // Principle queued with count=1 — next failure should make it 2
+    addPrincipleToLedger(stateDir, makePrinciple('P_012', {
+      evaluability: 'weak_heuristic',
+      compilationRetryCount: 1,
+    }));
+
+    const wctx = makeWctx(workspace, stateDir);
+    processCompilationBackfill(wctx, noopLogger);
+
+    const ledger = loadLedger(stateDir);
+    // Compilation fails (no trajectory data), so count increments
+    expect(ledger.tree.principles['P_012'].compilationRetryCount).toBe(2);
+    expect(ledger.tree.principles['P_012'].evaluability).toBe('weak_heuristic');
+  });
+
+  it('downgrades to manual_only after 5 consecutive failures', () => {
+    const workspace = makeTempDir();
+    const stateDir = makeStateDir(workspace);
+
+    // Principle at count=4 — next failure exhausts it
+    addPrincipleToLedger(stateDir, makePrinciple('P_011', {
+      evaluability: 'weak_heuristic',
+      compilationRetryCount: 4,
+    }));
+
+    const wctx = makeWctx(workspace, stateDir);
+    processCompilationBackfill(wctx, noopLogger);
+
+    const ledger = loadLedger(stateDir);
+    // Compilation fails (no trajectory), count becomes 5 >= 5, downgrades to manual_only
+    expect(ledger.tree.principles['P_011'].evaluability).toBe('manual_only');
+    expect(ledger.tree.principles['P_011'].compilationRetryCount).toBeUndefined();
+  });
+});