principles-disciple 1.19.0 → 1.21.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.19.0",
+  "version": "1.21.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/src/commands/archive-impl.ts

@@ -126,7 +126,11 @@ function _handleArchiveImpl(
   updateImplementation(stateDir, implId, {
     archivedAt: new Date().toISOString(),
   });
-  refreshPrincipleLifecycle(workspaceDir, stateDir);
+  try {
+    refreshPrincipleLifecycle(workspaceDir, stateDir);
+  } catch (err) {
+    console.warn('[archive-impl] Lifecycle refresh failed:', err instanceof Error ? err.stack : err);
+  }
 
   return {
     text: isZh

package/src/commands/disable-impl.ts

@@ -109,7 +109,11 @@ function _handleDisableImpl(
     disabledBy: sessionId || 'manual',
     disabledReason: reasonText,
   });
-  refreshPrincipleLifecycle(workspaceDir, stateDir);
+  try {
+    refreshPrincipleLifecycle(workspaceDir, stateDir);
+  } catch (err) {
+    console.warn('[disable-impl] Lifecycle refresh failed:', err instanceof Error ? err.stack : err);
+  }
 
   return {
     text: isZh

package/src/commands/nocturnal-review.ts

@@ -22,6 +22,7 @@
  */
 
 import * as fs from 'fs';
+import * as path from 'path';
 import {
   listDatasetRecords,
   getDatasetRecord,
@@ -31,6 +32,7 @@ import {
   type NocturnalDatasetRecord,
   type NocturnalReviewStatus,
 } from '../core/nocturnal-dataset.js';
+import { getPrincipleState, setPrincipleState } from '../core/principle-training-state.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
@@ -194,6 +196,16 @@ export function handleNocturnalReviewCommand(ctx: PluginCommandContext): PluginC
 
       const updated = updateReviewStatus(workspaceDir, fingerprint, 'approved_for_training', reason);
 
+      // #251: Sync approvedSampleCount in training store
+      try {
+        const stateDir = path.join(workspaceDir, '.state');
+        const state = getPrincipleState(stateDir, updated.principleId);
+        state.approvedSampleCount += 1;
+        setPrincipleState(stateDir, state);
+      } catch (err) {
+        console.warn(`[nocturnal-review] Failed to sync approvedSampleCount for ${updated.principleId}:`, err instanceof Error ? err.stack : err);
+      }
+
       return {
         text: zh
           ? `样本已批准用于训练:\n  fingerprint: ${updated.sampleFingerprint.substring(0, 16)}...\n  principleId: ${updated.principleId}\n  targetModelFamily: ${updated.targetModelFamily ?? '(none)'}\n  reason: ${updated.reviewReason}`

package/src/commands/promote-impl.ts

@@ -172,7 +172,11 @@ function _handlePromoteImpl(options: PromoteImplOptions): PluginCommandResult {
       disabledBy: undefined,
       disabledReason: undefined,
     });
-    refreshPrincipleLifecycle(workspaceDir, stateDir);
+    try {
+      refreshPrincipleLifecycle(workspaceDir, stateDir);
+    } catch (err) {
+      console.warn('[promote-impl] Lifecycle refresh failed (re-enable):', err instanceof Error ? err.stack : err);
+    }
 
     output += isZh
       ? `\n✅ 实现已重新启用: ${implId}\n   状态: disabled -> active`
@@ -225,7 +229,11 @@ function _handlePromoteImpl(options: PromoteImplOptions): PluginCommandResult {
   withLock(eventPath, () => {
     fs.writeFileSync(eventPath, JSON.stringify(promotionEvent, null, 2), 'utf-8');
   });
-  refreshPrincipleLifecycle(workspaceDir, stateDir);
+  try {
+    refreshPrincipleLifecycle(workspaceDir, stateDir);
+  } catch (err) {
+    console.warn('[promote-impl] Lifecycle refresh failed (promotion):', err instanceof Error ? err.stack : err);
+  }
 
   output += isZh
     ? `\n\n✅ 实现已晋升: ${implId}\n   状态: candidate -> active`

package/src/commands/rollback-impl.ts

@@ -185,7 +185,11 @@ function _handleRollbackImpl(
   withLock(rollbackPath, () => {
     fs.writeFileSync(rollbackPath, JSON.stringify(rollbackRecord, null, 2), 'utf-8');
   });
-  refreshPrincipleLifecycle(workspaceDir, stateDir);
+  try {
+    refreshPrincipleLifecycle(workspaceDir, stateDir);
+  } catch (err) {
+    console.warn('[rollback-impl] Lifecycle refresh failed:', err instanceof Error ? err.stack : err);
+  }
 
   let output = isZh
     ? `\n\u2705 \u56de\u6eda\u5b8c\u6210: ${implId}\n   \u72b6\u6001: active -> disabled\n   \u539f\u56e0: ${reasonText}`

package/src/core/nocturnal-snapshot-contract.ts

@@ -14,8 +14,9 @@ function isNonEmptyString(value: unknown): value is string {
   return typeof value === 'string' && value.trim().length > 0;
 }
 
-function isNumberOrNull(value: unknown): value is number | null {
-  return value === null || (typeof value === 'number' && Number.isFinite(value));
+/** #246: Stats fields must now be finite numbers — null is no longer accepted. */
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
 }
 
 export function validateNocturnalSnapshotIngress(
@@ -56,20 +57,20 @@ export function validateNocturnalSnapshotIngress(
   if (!isObjectRecord(stats)) {
     reasons.push('snapshot.stats must be an object');
   } else {
-    if (!isNumberOrNull(stats.totalAssistantTurns)) {
-      reasons.push('snapshot.stats.totalAssistantTurns must be a number or null');
+    if (!isFiniteNumber(stats.totalAssistantTurns)) {
+      reasons.push('snapshot.stats.totalAssistantTurns must be a finite number');
     }
-    if (!isNumberOrNull(stats.totalToolCalls)) {
-      reasons.push('snapshot.stats.totalToolCalls must be a number or null');
+    if (!isFiniteNumber(stats.totalToolCalls)) {
+      reasons.push('snapshot.stats.totalToolCalls must be a finite number');
     }
-    if (typeof stats.totalPainEvents !== 'number' || !Number.isFinite(stats.totalPainEvents)) {
+    if (!isFiniteNumber(stats.totalPainEvents)) {
       reasons.push('snapshot.stats.totalPainEvents must be a finite number');
     }
-    if (!isNumberOrNull(stats.totalGateBlocks)) {
-      reasons.push('snapshot.stats.totalGateBlocks must be a number or null');
+    if (!isFiniteNumber(stats.totalGateBlocks)) {
+      reasons.push('snapshot.stats.totalGateBlocks must be a finite number');
     }
-    if (!isNumberOrNull(stats.failureCount)) {
-      reasons.push('snapshot.stats.failureCount must be a number or null');
+    if (!isFiniteNumber(stats.failureCount)) {
+      reasons.push('snapshot.stats.failureCount must be a finite number');
     }
   }
 
@@ -85,21 +86,6 @@ export function validateNocturnalSnapshotIngress(
     }
   }
 
-  if (!isFallback && isObjectRecord(stats)) {
-    if (stats.totalAssistantTurns === null) {
-      reasons.push('non-fallback snapshot.stats.totalAssistantTurns must be a number');
-    }
-    if (stats.totalToolCalls === null) {
-      reasons.push('non-fallback snapshot.stats.totalToolCalls must be a number');
-    }
-    if (stats.totalGateBlocks === null) {
-      reasons.push('non-fallback snapshot.stats.totalGateBlocks must be a number');
-    }
-    if (stats.failureCount === null) {
-      reasons.push('non-fallback snapshot.stats.failureCount must be a number');
-    }
-  }
-
   if (reasons.length > 0) {
     return { status: 'invalid', reasons };
   }

package/src/core/nocturnal-trajectory-extractor.ts

@@ -116,15 +116,18 @@ export interface NocturnalSessionSnapshot {
   gateBlocks: NocturnalGateBlock[];
   /**
    * Summary statistics for quick triage.
-   * When _dataSource is 'pain_context_fallback', these fields are null
-   * to distinguish "no data" from "data is zero".
+   * #246: All fields are now number (never null).
+   * Previously null was used to mean "no trajectory data", but this caused
+   * downstream consumers to crash on arithmetic. The fallback path now
+   * queries the trajectory extractor for real data and falls back to 0.
+   * Use _dataSource === 'pain_context_fallback' to detect partial data.
    */
   stats: {
-    totalAssistantTurns: number | null;
-    totalToolCalls: number | null;
+    totalAssistantTurns: number;
+    totalToolCalls: number;
     totalPainEvents: number;
-    totalGateBlocks: number | null;
-    failureCount: number | null;
+    totalGateBlocks: number;
+    failureCount: number;
   };
   /**
    * #219: Marker for data source to identify fallback/partial stats.

package/src/core/principle-internalization/internalization-routing-policy.ts

@@ -121,14 +121,14 @@ export function recommendInternalizationRoute(
     principle.summary.repeatedErrorSignal === 0;
 
   if (principle.rules.length === 0) {
-    reasonCodes.push('no_material_rules');
+    reasonCodes.push('insufficient_data', 'no_material_rules');
     return {
       principleId: principle.principle.id,
       route: 'defer',
-      confidence: 95,
+      confidence: 50,
       reasonCodes,
       evidenceSummary,
-      nextAction: 'Define at least one concrete rule before choosing an internalization route.',
+      nextAction: 'No rules defined for this principle. Create at least one rule via pain→principle→rule pipeline before internalization routing can produce meaningful recommendations.',
     };
   }
 

package/src/core/principle-internalization/lifecycle-metrics.ts

@@ -11,6 +11,8 @@ export interface RuleMetricResult {
 }
 
 export interface PrincipleAdherenceResult {
+  /** True when no rules exist — all numeric fields are defaults, not computed values */
+  insufficientData?: boolean;
   adherenceRate: number;
   averageRuleCoverage: number;
   averageFalsePositiveRate: number;
@@ -108,6 +110,7 @@ export function computePrincipleAdherence(
 
   if (principle.rules.length === 0) {
     return {
+      insufficientData: true,
       adherenceRate: 0,
       averageRuleCoverage: 0,
       averageFalsePositiveRate: 0,

package/src/service/evolution-worker.ts

@@ -132,9 +132,17 @@ async function runWorkflowWatchdog(
             if (dataSource === 'pain_context_fallback') {
               details.push(`fallback_snapshot: nocturnal workflow ${wf.workflow_id} uses pain-context fallback (stats may be incomplete)`);
             }
-            const stats = snapshot.stats as Record<string, number | null> | undefined;
-            if (stats && stats.totalAssistantTurns === null && stats.totalToolCalls === null && stats.totalPainEvents === 0 && stats.totalGateBlocks === null) {
-              details.push(`fallback_snapshot_stats: nocturnal workflow ${wf.workflow_id} has null stats (data unavailable)`);
+            const stats = snapshot.stats as Record<string, number> | undefined;
+            // #246: Stats are now always number (never null). Detect "empty" fallback:
+            // fallback + all counts zero means no real data was available.
+            // NOTE: totalAssistantTurns may be 0 even for valid sessions because
+            // listRecentNocturnalCandidateSessions (used in fallback path) does not
+            // populate assistantTurnCount (only getNocturnalSessionSnapshot does).
+            // We use totalToolCalls=0 as the primary indicator instead.
+            if (stats && dataSource === 'pain_context_fallback' &&
+                stats.totalToolCalls === 0 && stats.totalGateBlocks === 0 &&
+                stats.failureCount === 0) {
+              details.push(`fallback_snapshot_stats: nocturnal workflow ${wf.workflow_id} has empty fallback stats (no trajectory data found)`);
             }
           }
         } catch { /* ignore malformed metadata */ }
@@ -335,7 +343,10 @@ function isSessionAtOrBeforeTriggerTime(
     return true;
 }
 
-function buildFallbackNocturnalSnapshot(sleepTask: EvolutionQueueItem): NocturnalSessionSnapshot | null {
+function buildFallbackNocturnalSnapshot(
+    sleepTask: EvolutionQueueItem,
+    extractor?: ReturnType<typeof createNocturnalTrajectoryExtractor> | null
+): NocturnalSessionSnapshot | null {
     const painContext = sleepTask.recentPainContext;
     if (!painContext) {
         return null;
@@ -349,6 +360,30 @@ function buildFallbackNocturnalSnapshot(sleepTask: EvolutionQueueItem): Nocturna
         createdAt: painContext.mostRecent.timestamp,
     }] : [];
 
+    // #246: Try to extract real session stats from trajectory DB for the pain session.
+    // The main path tries getNocturnalSessionSnapshot which returns null when no session
+    // exists. Here we attempt a lighter query via listRecentNocturnalCandidateSessions
+    // to at least get summary counts for the pain-triggering session.
+    let realStats: { totalAssistantTurns: number; totalToolCalls: number; failureCount: number; totalGateBlocks: number } | null = null;
+    if (extractor && painContext.mostRecent?.sessionId) {
+        try {
+            // #246-fix: Use minToolCalls=0 to avoid filtering out sessions with 0 tool calls.
+            // The pain-triggering session may have no tool calls but still be worth tracking.
+            const summaries = extractor.listRecentNocturnalCandidateSessions({ limit: 300, minToolCalls: 0 });
+            const match = summaries.find(s => s.sessionId === painContext.mostRecent!.sessionId);
+            if (match) {
+                realStats = {
+                    totalAssistantTurns: match.assistantTurnCount,
+                    totalToolCalls: match.toolCallCount,
+                    failureCount: match.failureCount,
+                    totalGateBlocks: match.gateBlockCount,
+                };
+            }
+        } catch {
+            // Best effort — non-fatal
+        }
+    }
+
     return {
         sessionId: painContext.mostRecent?.sessionId || sleepTask.id,
         startedAt: sleepTask.timestamp,
@@ -359,11 +394,11 @@ function buildFallbackNocturnalSnapshot(sleepTask: EvolutionQueueItem): Nocturna
         painEvents: fallbackPainEvents,
         gateBlocks: [],
         stats: {
-            totalAssistantTurns: null,
-            totalToolCalls: null,
-            failureCount: null,
+            totalAssistantTurns: realStats?.totalAssistantTurns ?? 0,
+            totalToolCalls: realStats?.totalToolCalls ?? 0,
+            failureCount: realStats?.failureCount ?? 0,
             totalPainEvents: painContext.recentPainCount,
-            totalGateBlocks: null,
+            totalGateBlocks: realStats?.totalGateBlocks ?? 0,
         },
         _dataSource: 'pain_context_fallback',
     };
@@ -1466,8 +1501,9 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                     } else {
                         // Phase 1: Build trajectory snapshot for Nocturnal pipeline
                         // Priority: Pain signal sessionId → Task ID → Recent session with violations
+                        let extractor: ReturnType<typeof createNocturnalTrajectoryExtractor> | null = null;
                         try {
-                            const extractor = createNocturnalTrajectoryExtractor(wctx.workspaceDir);
+                            extractor = createNocturnalTrajectoryExtractor(wctx.workspaceDir);
 
                             // 1. Try exact session ID from pain signal (most accurate)
                             const painSessionId = sleepTask.recentPainContext?.mostRecent?.sessionId;
@@ -1516,8 +1552,8 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
 
                         // Phase 2: If no trajectory data, try pain-context fallback
                         if (!snapshotData && sleepTask.recentPainContext) {
-                            logger?.warn?.(`[PD:EvolutionWorker] Using pain-context fallback for ${sleepTask.id}: trajectory stats unavailable (stats will be null)`);
-                            snapshotData = buildFallbackNocturnalSnapshot(sleepTask) ?? undefined;
+                            logger?.warn?.(`[PD:EvolutionWorker] Using pain-context fallback for ${sleepTask.id}: trajectory snapshot unavailable, will try session summary from extractor`);
+                            snapshotData = buildFallbackNocturnalSnapshot(sleepTask, extractor) ?? undefined;
                         }
 
                         const snapshotValidation = validateNocturnalSnapshotIngress(snapshotData);

package/src/service/nocturnal-service.ts

@@ -98,9 +98,24 @@ import {
 } from './nocturnal-runtime.js';
 import { NocturnalPathResolver } from '../core/nocturnal-paths.js';
 import { registerSample } from '../core/nocturnal-dataset.js';
+import { getPrincipleState, setPrincipleState } from '../core/principle-training-state.js';
 import type { Implementation } from '../types/principle-tree-schema.js';
 import { validateNocturnalSnapshotIngress } from '../core/nocturnal-snapshot-contract.js';
 
+// ---------------------------------------------------------------------------
+// #251: Sync trainingStore sample counts after registration
+// ---------------------------------------------------------------------------
+
+function incrementGeneratedSampleCount(stateDir: string, principleId: string): void {
+  try {
+    const state = getPrincipleState(stateDir, principleId);
+    state.generatedSampleCount += 1;
+    setPrincipleState(stateDir, state);
+  } catch (err) {
+    console.warn(`[nocturnal-service] Failed to sync generatedSampleCount for ${principleId}:`, err instanceof Error ? err.stack : err);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -467,7 +482,11 @@ function persistCodeCandidate(
       implementationId,
       createdAt: now,
     });
-    refreshPrincipleLifecycle(workspaceDir, stateDir);
+    try {
+      refreshPrincipleLifecycle(workspaceDir, stateDir);
+    } catch (err) {
+      console.warn('[nocturnal-service] Lifecycle refresh failed after code candidate persistence:', err instanceof Error ? err.stack : err);
+    }
     return {
       status: 'persisted_candidate',
       ruleResolution: {
@@ -993,7 +1012,10 @@ export function executeNocturnalReflection(
   // Approved artifacts must enter the dataset registry so they can be reviewed
   // before export. Without this, new samples never appear in the review queue.
   try {
-    registerSample(workspaceDir, arbiterResult.artifact, persistedPath, null);
+    const regResult = registerSample(workspaceDir, arbiterResult.artifact, persistedPath, null);
+    if (regResult.isNew) {
+      incrementGeneratedSampleCount(stateDir, arbiterResult.artifact.principleId);
+    }
   } catch (err) {
     // Non-fatal: artifact is persisted, registry is secondary.
     // Log but don't fail the run.
@@ -1380,7 +1402,10 @@ async function executeNocturnalReflectionWithAdapter(
 
   // Step 8: Register in dataset lineage
   try {
-    registerSample(workspaceDir, arbiterResult.artifact, persistedPath, null);
+    const regResult = registerSample(workspaceDir, arbiterResult.artifact, persistedPath, null);
+    if (regResult.isNew) {
+      incrementGeneratedSampleCount(stateDir, arbiterResult.artifact.principleId);
+    }
   } catch (err) {
     console.warn(`[nocturnal-service] Failed to register sample in dataset registry: ${String(err)}`);
   }

package/tests/core/nocturnal-snapshot-contract.test.ts

@@ -54,10 +54,35 @@ describe('validateNocturnalSnapshotIngress', () => {
       toolCalls: [],
       painEvents: [],
       gateBlocks: [],
+      stats: {
+        totalAssistantTurns: 0,
+        totalToolCalls: 0,
+        totalPainEvents: 0,
+        totalGateBlocks: 0,
+        failureCount: 0,
+      },
+      _dataSource: 'pain_context_fallback',
+    });
+
+    expect(result.status).toBe('invalid');
+    expect(result.reasons).toContain('fallback snapshot must contain at least one pain signal');
+  });
+
+  // #246: null stats fields should now be rejected (they used to be accepted for fallback)
+  it('rejects null values in stats fields', () => {
+    const result = validateNocturnalSnapshotIngress({
+      sessionId: 'session-1',
+      startedAt: '2026-04-10T00:00:00.000Z',
+      updatedAt: '2026-04-10T00:00:00.000Z',
+      assistantTurns: [],
+      userTurns: [],
+      toolCalls: [],
+      painEvents: [{ source: 'test', score: 5, severity: 'high', reason: 'test', createdAt: '2026-04-10T00:00:00.000Z' }],
+      gateBlocks: [],
       stats: {
         totalAssistantTurns: null,
         totalToolCalls: null,
-        totalPainEvents: 0,
+        totalPainEvents: 1,
         totalGateBlocks: null,
         failureCount: null,
       },
@@ -65,6 +90,32 @@ describe('validateNocturnalSnapshotIngress', () => {
     });
 
     expect(result.status).toBe('invalid');
-    expect(result.reasons).toContain('fallback snapshot must contain at least one pain signal');
+    expect(result.reasons).toContain('snapshot.stats.totalAssistantTurns must be a finite number');
+    expect(result.reasons).toContain('snapshot.stats.totalToolCalls must be a finite number');
+    expect(result.reasons).toContain('snapshot.stats.totalGateBlocks must be a finite number');
+    expect(result.reasons).toContain('snapshot.stats.failureCount must be a finite number');
+  });
+
+  it('accepts fallback snapshot with valid stats and pain signal', () => {
+    const result = validateNocturnalSnapshotIngress({
+      sessionId: 'session-1',
+      startedAt: '2026-04-10T00:00:00.000Z',
+      updatedAt: '2026-04-10T00:00:00.000Z',
+      assistantTurns: [],
+      userTurns: [],
+      toolCalls: [],
+      painEvents: [{ source: 'test', score: 5, severity: 'high', reason: 'test', createdAt: '2026-04-10T00:00:00.000Z' }],
+      gateBlocks: [],
+      stats: {
+        totalAssistantTurns: 0,
+        totalToolCalls: 0,
+        totalPainEvents: 1,
+        totalGateBlocks: 0,
+        failureCount: 0,
+      },
+      _dataSource: 'pain_context_fallback',
+    });
+
+    expect(result.status).toBe('valid');
   });
 });