principles-disciple 1.28.0 → 1.28.2

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.28.0",
+  "version": "1.28.2",
   "skills": [
     "./skills"
   ],
@@ -76,8 +76,8 @@
     }
   },
   "buildFingerprint": {
-    "gitSha": "27d380ef1db5",
-    "bundleMd5": "e6f2b6946eddc217169568fc45c5569e",
-    "builtAt": "2026-04-13T08:32:02.125Z"
+    "gitSha": "25bfc2bb209f",
+    "bundleMd5": "b735aa483374dd2c7071295b11161676",
+    "builtAt": "2026-04-13T14:25:24.799Z"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.28.0",
+  "version": "1.28.2",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",
@@ -40,14 +40,14 @@
     "@testing-library/react": "^16.3.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/micromatch": "^4.0.10",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.6.0",
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
     "@types/ws": "^8.5.13",
     "@typescript-eslint/eslint-plugin": "^8.58.0",
     "@typescript-eslint/parser": "^8.58.0",
     "@vitest/coverage-v8": "^4.1.0",
-    "esbuild": "^0.27.4",
+    "esbuild": "^0.28.0",
     "eslint": "^10.1.0",
     "jsdom": "^29.0.1",
     "typescript": "^6.0.2",
@@ -64,7 +64,7 @@
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.48",
-    "better-sqlite3": "^12.8.0",
+    "better-sqlite3": "^12.9.0",
     "lucide-react": "^1.7.0",
     "micromatch": "^4.0.8",
     "react": "^19.2.0",

package/scripts/validate-live-path.ts

@@ -20,6 +20,7 @@
  *   WORKSPACE_DIR - Optional workspace directory (defaults to process.cwd())
  */
 
+import * as Database from 'better-sqlite3';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -33,7 +34,6 @@ const LOCK_STALE_MS = 30_000;
 const WORKSPACE_DIR = process.env.WORKSPACE_DIR || process.cwd();
 const STATE_DIR = path.join(WORKSPACE_DIR, '.state');
 const QUEUE_PATH = path.join(STATE_DIR, 'EVOLUTION_QUEUE');
-const QUEUE_LOCK_PATH = QUEUE_PATH + LOCK_SUFFIX;
 const LEDGER_PATH = path.join(STATE_DIR, 'principle_training_state.json');
 const DB_PATH = path.join(STATE_DIR, 'subagent_workflows.db');
 
@@ -80,17 +80,14 @@ async function acquireLockAsync(filePath: string, options: {
   baseRetryDelayMs?: number;
   lockStaleMs?: number;
 } = {}): Promise<LockContext> {
-  const opts = {
-    lockSuffix: LOCK_SUFFIX,
-    maxRetries: LOCK_MAX_RETRIES,
-    baseRetryDelayMs: LOCK_RETRY_DELAY_MS,
-    lockStaleMs: LOCK_STALE_MS,
-    ...options,
-  };
+  const lockSuffix = options.lockSuffix ?? LOCK_SUFFIX;
+  const maxRetries = options.maxRetries ?? LOCK_MAX_RETRIES;
+  const baseRetryDelayMs = options.baseRetryDelayMs ?? LOCK_RETRY_DELAY_MS;
+  const lockStaleMs = options.lockStaleMs ?? LOCK_STALE_MS;
   const { pid } = process;
-  const lockPath = filePath + opts.lockSuffix;
+  const lockPath = filePath + lockSuffix;
 
-  for (let attempt = 0; attempt < opts.maxRetries!; attempt++) {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
     try {
       // Check if lock file exists and is stale
       if (fs.existsSync(lockPath)) {
@@ -100,11 +97,11 @@ async function acquireLockAsync(filePath: string, options: {
         const lockAge = Date.now() - lockStats.mtimeMs;
 
         // Clean up stale lock
-        if (lockAge > opts.lockStaleMs!) {
+        if (lockAge > lockStaleMs) {
           fs.unlinkSync(lockPath);
         } else if (lockPid !== pid) {
           // Lock held by another process
-          await new Promise(resolve => setTimeout(resolve, opts.baseRetryDelayMs!));
+          await new Promise(resolve => setTimeout(resolve, baseRetryDelayMs));
           continue;
         }
       }
@@ -125,17 +122,20 @@ async function acquireLockAsync(filePath: string, options: {
         },
       };
     } catch (error: unknown) {
-      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
-        if (attempt < opts.maxRetries! - 1) {
-          await new Promise(resolve => setTimeout(resolve, opts.baseRetryDelayMs!));
+      const err = error as { code?: string };
+      if (err.code === 'EEXIST') {
+        if (attempt < maxRetries - 1) {
+          await new Promise(resolve => setTimeout(resolve, baseRetryDelayMs));
           continue;
         }
       }
-      throw new Error(`Failed to acquire lock for ${filePath}: ${String(error)}`);
+      const lockError = new Error(`Failed to acquire lock for ${filePath}: ${String(error)}`);
+      lockError.cause = error;
+      throw lockError;
     }
   }
 
-  throw new Error(`Failed to acquire lock for ${filePath} after ${opts.maxRetries} attempts`);
+  throw new Error(`Failed to acquire lock for ${filePath} after ${maxRetries} attempts`);
 }
 
 function releaseLock(ctx: LockContext): void {
@@ -225,7 +225,6 @@ function listNocturnalWorkflows(): WorkflowRow[] {
     return [];
   }
 
-  const Database = require('better-sqlite3');
   const db = new Database(DB_PATH, { readonly: true });
   const rows = db.prepare(`
     SELECT workflow_id, workflow_type, state, metadata_json, created_at
@@ -279,6 +278,7 @@ async function main() {
   const verbose = process.argv.includes('--verbose');
 
   // 1. Check bootstrapped rules
+  // eslint-disable-next-line @typescript-eslint/init-declarations
   let rules: LedgerRule[];
   try {
     rules = loadBootstrappedRules();

package/src/commands/context.ts

@@ -305,6 +305,7 @@ function showHelp(isZh: boolean): string {
 /**
  * Main command handler
  */
+    // eslint-disable-next-line complexity -- complexity 15, refactor candidate
 export function handleContextCommand(ctx: PluginCommandContext): PluginCommandResult {
     const workspaceDir = getWorkspaceDir(ctx);
     const args = (ctx.args || '').trim().split(/\s+/);

package/src/commands/disable-impl.ts

@@ -70,6 +70,7 @@ function _handleListActive(
 }
 
  
+    // eslint-disable-next-line complexity -- complexity 15, refactor candidate
 function _handleDisableImpl(
   workspaceDir: string,
   stateDir: string,
@@ -130,6 +131,7 @@ function _handleDisableImpl(
  *   /pd-disable-impl <implId>                    - Disable an implementation
  *   /pd-disable-impl <implId> --reason "<reason>" - Disable with reason
  */
+    // eslint-disable-next-line complexity -- complexity 12, refactor candidate
 export function handleDisableImplCommand(ctx: PluginCommandContext): PluginCommandResult {
   const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
   const {stateDir} = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir });

package/src/commands/evolution-status.ts

@@ -46,6 +46,7 @@ function formatRouteRecommendations(
 }
 
  
+    // eslint-disable-next-line complexity -- complexity 15, refactor candidate
 function buildEnglishOutput(
   workspaceDir: string,
   sessionId: string | null,
@@ -98,6 +99,7 @@ function buildEnglishOutput(
 }
 
  
+    // eslint-disable-next-line complexity -- complexity 15, refactor candidate
 function buildChineseOutput(
   workspaceDir: string,
   sessionId: string | null,

package/src/commands/focus.ts

@@ -47,6 +47,7 @@ function getWorkspaceDir(ctx: PluginCommandContext): string {
  * - 清理：Working Memory 超过 10 条记录时保留最近 10 条
  * - 验证：文件引用指向不存在的文件时移除
  */
+    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
 function compressFocusContent(content: string, workspaceDir?: string): string {
   // 首先使用 cleanupStaleInfo 进行基础清理
   let result = cleanupStaleInfo(content, workspaceDir);
@@ -346,6 +347,7 @@ ${milestoneNote ? `${milestoneNote}\n` : ''}
 /**
  * 回滚到历史版本
  */
+    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
 function rollbackFocus(workspaceDir: string, index: number, isZh: boolean): string {
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir });
   const focusPath = wctx.resolve('CURRENT_FOCUS');

package/src/commands/nocturnal-train.ts

@@ -30,6 +30,7 @@ import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.
 import {
   type TrainerBackendKind,
   type HardwareTier,
+  type TrainingExperimentResult,
 } from '../core/external-training-contract.js';
 import {
   TrainingProgram,
@@ -270,14 +271,11 @@ Hardware tiers:
       // This closes the gap in the create-experiment -> trainer -> import-result chain.
       // NOTE: This blocks until training completes (could be minutes).
       if (runNow) {
-         
-        const {spec} = createResult;
         const baseDir = TRAINER_SCRIPTS_DIR;
         const scriptPath = path.join(baseDir, 'main.py');
         const specPath = path.join(baseDir, `experiment-${spec.experimentId}.json`);
-         
-        const {outputDir} = spec;
-        const resultFilePath = path.join(outputDir, `result-${spec.experimentId}.json`);
+
+        const resultFilePath = path.join(spec.outputDir, `result-${spec.experimentId}.json`);
 
         // Write spec file
         const specDir = path.dirname(specPath);
@@ -287,7 +285,7 @@ Hardware tiers:
         fs.writeFileSync(specPath, JSON.stringify(spec, null, 2), 'utf-8');
 
          
-        let trainerResult!: import('../core/external-training-contract.js').TrainingExperimentResult;
+        let trainerResult!: TrainingExperimentResult;
 
         try {
           if (spec.backend === 'dry-run') {

package/src/commands/pain.ts

@@ -127,20 +127,17 @@ export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResul
     
     // Determine Mental Mode (aligned with prompt.ts logic)
      
-    let mentalMode = '';
-    if (isZh) {
-        if (gfi >= 70) mentalMode = '🚑 救赎模式 (HUMBLE_RECOVERY)';
-        else if (gfi >= 40) mentalMode = '🤝 安抚模式 (CONCILIATORY)';
-        else mentalMode = '⚡ 高效模式 (EFFICIENT)';
-    } else {
-        if (gfi >= 70) mentalMode = '🚑 HUMBLE_RECOVERY';
-        else if (gfi >= 40) mentalMode = '🤝 CONCILIATORY';
-        else mentalMode = '⚡ EFFICIENT';
-    }
+    const mentalMode = isZh
+        ? gfi >= 70 ? '🚑 救赎模式 (HUMBLE_RECOVERY)'
+        : gfi >= 40 ? '🤝 安抚模式 (CONCILIATORY)'
+        : '⚡ 高效模式 (EFFICIENT)'
+        : gfi >= 70 ? '🚑 HUMBLE_RECOVERY'
+        : gfi >= 40 ? '🤝 CONCILIATORY'
+        : '⚡ EFFICIENT';
     
     // Determine health status based on GFI
      
-    let healthLabel = 'Healthy';
+    let healthLabel: string;
     let suggestionText = '';
 
     if (isZh) {
@@ -219,6 +216,7 @@ export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResul
  * Handle /pd-status empathy subcommand
  */
  
+    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
 function handleEmpathySubcommand(
     wctx: WorkspaceContext,
     args: string,

package/src/commands/pd-reflect.ts

@@ -5,7 +5,7 @@
  * This command must operate on an explicitly resolved active workspace.
  */
 
-import { PluginCommandDefinition, PluginCommandContext, PluginCommandResult, OpenClawPluginApi } from '../openclaw-sdk.js';
+import type { PluginCommandDefinition, PluginCommandContext, PluginCommandResult, OpenClawPluginApi } from '../openclaw-sdk.js';
 import { acquireQueueLock, EVOLUTION_QUEUE_LOCK_SUFFIX } from '../service/evolution-worker.js';
 import * as fs from 'fs';
 import * as path from 'path';

package/src/commands/principle-rollback.ts

@@ -1,6 +1,7 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext } from '../openclaw-sdk.js';
 
+    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
 export function handlePrincipleRollbackCommand(ctx: PluginCommandContext): { text: string } {
   const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
   const argText = (ctx.args || '').trim();

package/src/commands/rollback-impl.ts

@@ -41,6 +41,7 @@ function getAllImplementations(stateDir: string): Implementation[] {
  *   /pd-rollback-impl <implId>                      - Rollback current active
  *   /pd-rollback-impl <implId> --reason "<reason>"  - Rollback with reason
  */
+    // eslint-disable-next-line complexity -- complexity 12, refactor candidate
 export function handleRollbackImplCommand(ctx: PluginCommandContext): PluginCommandResult {
   const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
   const {stateDir} = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir });

package/src/core/adaptive-thresholds.ts

@@ -407,6 +407,7 @@ export function getDetailedThresholdState(
  * @param signals - Observable signals
  * @returns UpdateThresholdResult describing the most significant change
  */
+    // eslint-disable-next-line complexity -- complexity 15, refactor candidate
 export function adjustThresholdsFromSignals(
   stateDir: string,
   signals: ThresholdSignals

package/src/core/bootstrap-rules.ts

@@ -30,7 +30,7 @@ export interface BootstrapResult {
  * @returns Array of principle IDs sorted by observedViolationCount (descending)
  * @throws Error if no deterministic principles found
  */
-export function selectPrinciplesForBootstrap(stateDir: string, limit: number = 3): string[] {
+export function selectPrinciplesForBootstrap(stateDir: string, limit = 3): string[] {
   // Load training store to get evaluability and violation data
   const store = loadStore(stateDir);
 
@@ -76,7 +76,7 @@ export function selectPrinciplesForBootstrap(stateDir: string, limit: number = 3
  * @returns Array of results indicating created or skipped status
  * @throws Error if no deterministic principles found
  */
-export function bootstrapRules(stateDir: string, limit: number = 3): BootstrapResult[] {
+export function bootstrapRules(stateDir: string, limit = 3): BootstrapResult[] {
   // Select principles for bootstrap
   const selectedPrincipleIds = selectPrinciplesForBootstrap(stateDir, limit);
 
@@ -107,7 +107,7 @@ export function bootstrapRules(stateDir: string, limit: number = 3): BootstrapRe
 
     // Create stub rule
     const now = new Date().toISOString();
-    const rule = createRule(stateDir, {
+    createRule(stateDir, {
       id: ruleId,
       version: 1,
       name: `Stub bootstrap rule for ${principleId}`,

package/src/core/dictionary.ts

@@ -116,6 +116,7 @@ export class PainDictionary {
         }
     }
 
+    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
     match(text: string): { ruleId: string; severity: number } | undefined {
         if (shouldIgnorePainProtocolText(text)) return undefined;
 

package/src/core/empathy-keyword-matcher.ts

@@ -207,6 +207,7 @@ export function matchEmpathyKeywords(
  * This is called when the empathy optimizer subagent completes its analysis
  * and returns suggested updates to the keyword store.
  */
+    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
 export function applyKeywordUpdates(
   store: EmpathyKeywordStore,
   updates: Record<string, {

package/src/core/event-log.ts

@@ -244,6 +244,7 @@ export class EventLog {
   }
 
    
+    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
   private getEventDedupKey(entry: EventLogEntry): string {
     const eventId = typeof (entry.data as { eventId?: unknown } | undefined)?.eventId === 'string'
       ? String((entry.data as { eventId?: string }).eventId)
@@ -340,6 +341,7 @@ export class EventLog {
    * @param range 'today' | 'week' | 'session'
    * @param sessionId Optional session ID for session-scoped stats
    */
+    // eslint-disable-next-line complexity -- complexity 12, refactor candidate
   getEmpathyStats(range: 'today' | 'week' | 'session', sessionId?: string): EmpathyEventStats {
     const now = new Date();
     const today = this.formatDate(now);

package/src/core/evolution-engine.ts

@@ -165,6 +165,7 @@ export class EvolutionEngine {
 
   // ===== 记录失败 =====
 
+    // eslint-disable-next-line complexity -- complexity 12, refactor candidate
   public recordFailure(
     toolName: string,
     options?: {

package/src/core/external-training-contract.ts

@@ -285,6 +285,7 @@ export interface ValidationResult {
  * @param result - The trainer result to validate
  * @returns ValidationResult indicating pass/fail and any errors
  */
+    // eslint-disable-next-line complexity -- complexity 11, slightly over threshold
 export function validateTrainerResult(
   spec: TrainingExperimentSpec,
   result: TrainingExperimentResult

package/src/core/focus-history.ts

@@ -265,6 +265,7 @@ export function compressFocus(focusPath: string, newContent: string): {
  * @param content CURRENT_FOCUS.md 内容
  * @param maxLines 最大行数
  */
+    // eslint-disable-next-line complexity -- complexity 12, refactor candidate
 export function extractSummary(content: string, maxLines = 30): string {
   const lines = content.split('\n');
   const sections: { [key: string]: string[] } = {
@@ -805,6 +806,7 @@ function generateWorkingMemorySection(snapshot: WorkingMemorySnapshot): string {
 /**
  * 生成工作记忆注入字符串（用于 prompt 注入）
  */
+    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
 export function workingMemoryToInjection(snapshot: WorkingMemorySnapshot | null): string {
   if (!snapshot) return '';
   
@@ -884,6 +886,7 @@ interface CompressionConfig {
  * @param stateDir state 目录路径
  * @returns 压缩配置
  */
+    // eslint-disable-next-line complexity -- complexity 11, slightly over threshold
 function loadCompressionConfig(stateDir?: string): CompressionConfig {
   if (!stateDir) {
     return DEFAULT_COMPRESSION_CONFIG;

package/src/core/init.ts

@@ -34,6 +34,7 @@ function hasOutdatedCoreGuidance(file: string, content: string): boolean {
  * Ensures that the workspace has the necessary template files for Principles Disciple.
  * This function flattens 'core' templates to the root so OpenClaw can find them.
  */
+    // eslint-disable-next-line complexity -- complexity 14, refactor candidate
 export function ensureWorkspaceTemplates(api: OpenClawPluginApi, workspaceDir: string, language = 'en') {
     try {
         const __filename = fileURLToPath(import.meta.url);

package/src/core/merge-gate-audit.ts

@@ -364,7 +364,7 @@ function validateSingleReplayReport(reportPath: string): ReplayValidationCategor
     return 'missing_evidence_summary';
   }
 
-  const evidenceSummary = (parsed as ReplayReport).evidenceSummary;
+  const evidenceSummary = parsed.evidenceSummary;
   if (parsed.overallDecision === 'pass' && evidenceSummary.totalSamples === 0) {
     return 'unsupported_pass';
   }

package/src/core/nocturnal-arbiter.ts

@@ -159,6 +159,7 @@ export interface TrinityStageValidationResult {
  * Validate a Dreamer output contract.
  * Ensures the output is well-formed before passing to Philosopher.
  */
+    // eslint-disable-next-line complexity -- complexity 11, slightly over threshold
 export function validateDreamerOutput(output: unknown): TrinityStageValidationResult {
   const failures: string[] = [];
 
@@ -237,6 +238,7 @@ export function validateDreamerOutput(output: unknown): TrinityStageValidationRe
  * Validate a Philosopher output contract.
  * Ensures the output is well-formed before passing to Scribe.
  */
+    // eslint-disable-next-line complexity -- complexity 14, refactor candidate
 export function validatePhilosopherOutput(output: unknown): TrinityStageValidationResult {
   const failures: string[] = [];
 
@@ -260,6 +262,7 @@ export function validatePhilosopherOutput(output: unknown): TrinityStageValidati
     failures.push('Philosopher output must have a judgments array');
   } else {
     // Validate each judgment
+    // eslint-disable-next-line complexity -- complexity 13, refactor candidate
     obj.judgments.forEach((judgment: unknown, idx: number) => {
       if (judgment === null || judgment === undefined || typeof judgment !== 'object') {
         failures.push(`Philosopher judgment at index ${idx} is not an object`);

package/src/core/nocturnal-candidate-scoring.ts

@@ -116,6 +116,23 @@ export const DEFAULT_SCORING_WEIGHTS: ScoringWeights = {
   confidence: 0.15,
 };
 
+/**
+ * Result of diversity validation on Dreamer candidates.
+ * Soft enforcement: result is informational, never gates the pipeline.
+ */
+export interface DiversityValidationResult {
+  /** Whether candidates passed diversity checks */
+  diversityCheckPassed: boolean;
+  /** Whether at least 2 distinct risk levels were present */
+  riskLevelDiversity: boolean;
+  /** Whether no candidate pair exceeded keyword overlap threshold */
+  keywordOverlapPassed: boolean;
+  /** Highest pairwise keyword overlap score (for telemetry) */
+  maxOverlapScore: number;
+  /** Human-readable summary of check results */
+  details: string;
+}
+
 // ---------------------------------------------------------------------------
 // Scoring Logic
 // ---------------------------------------------------------------------------
@@ -232,6 +249,120 @@ export function checkThresholds(
   return [failedThresholds.length === 0, failedThresholds];
 }
 
+/**
+ * Validate that Dreamer candidates are strategically diverse.
+ *
+ * DIVER-03: Checks risk level diversity (Set.size >= 2 when candidates >= 2)
+ * and keyword overlap similarity (reject if intersection / max(|A|, |B|) > 0.8
+ * for words > 3 chars per D-05).
+ *
+ * This is SOFT enforcement: returns a result, never throws.
+ * Pipeline continues regardless of diversityCheckPassed value.
+ *
+ * @param candidates - Dreamer candidates to validate
+ * @returns DiversityValidationResult with pass/fail details
+ */
+export function validateCandidateDiversity(
+  candidates: DreamerCandidate[],
+): DiversityValidationResult {
+  // Edge cases: empty, null, or single candidate always passes
+  if (!candidates || candidates.length <= 1) {
+    return {
+      diversityCheckPassed: true,
+      riskLevelDiversity: true,
+      keywordOverlapPassed: true,
+      maxOverlapScore: 0,
+      details: candidates?.length === 1
+        ? 'Single candidate — diversity check not applicable'
+        : 'No candidates to validate',
+    };
+  }
+
+  // Check 1: Risk level diversity (D-05)
+  const riskLevels = new Set(
+    candidates
+      .map(c => c.riskLevel)
+      .filter((r): r is "low" | "medium" | "high" => typeof r === 'string')
+  );
+  // If NO candidates have riskLevel, skip risk diversity check (graceful degradation)
+  const riskLevelDiversity = riskLevels.size === 0 || riskLevels.size >= 2;
+
+  // Check 2: Keyword overlap (D-05: intersection / max(|A|, |B|) for words > 3 chars)
+  let maxOverlapScore = 0;
+  let keywordOverlapPassed = true;
+
+  for (let i = 0; i < candidates.length; i++) {
+    for (let j = i + 1; j < candidates.length; j++) {
+      const overlap = computeKeywordOverlap(
+        candidates[i].betterDecision ?? '',
+        candidates[j].betterDecision ?? '',
+      );
+      if (overlap > maxOverlapScore) {
+        maxOverlapScore = overlap;
+      }
+      if (overlap > 0.8) {
+        keywordOverlapPassed = false;
+      }
+    }
+  }
+
+  const diversityCheckPassed = riskLevelDiversity && keywordOverlapPassed;
+
+  // Build details string
+  const parts: string[] = [];
+  if (!riskLevelDiversity) {
+    parts.push(`Risk levels not diverse (found: ${[...riskLevels].join(', ') || 'none'})`);
+  }
+  if (!keywordOverlapPassed) {
+    parts.push(`Keyword overlap too high (max: ${maxOverlapScore.toFixed(2)})`);
+  }
+
+  return {
+    diversityCheckPassed,
+    riskLevelDiversity,
+    keywordOverlapPassed,
+    maxOverlapScore: Math.round(maxOverlapScore * 100) / 100,
+    details: diversityCheckPassed
+      ? 'Diversity check passed'
+      : parts.join('; '),
+  };
+}
+
+/**
+ * Compute keyword overlap between two strings.
+ * Algorithm: intersection / max(|A|, |B|) for words > 3 chars (per D-05).
+ * Returns value between 0 and 1.
+ */
+function computeKeywordOverlap(textA: string, textB: string): number {
+  const wordsA = extractKeywords(textA);
+  const wordsB = extractKeywords(textB);
+
+  if (wordsA.length === 0 && wordsB.length === 0) return 0;
+  if (wordsA.length === 0 || wordsB.length === 0) return 0;
+
+  const setA = new Set(wordsA);
+  const setB = new Set(wordsB);
+
+  let intersection = 0;
+  for (const word of setA) {
+    if (setB.has(word)) intersection++;
+  }
+
+  const denominator = Math.max(setA.size, setB.size);
+  return denominator === 0 ? 0 : intersection / denominator;
+}
+
+/**
+ * Extract keywords from text: words > 3 characters, lowercased.
+ */
+function extractKeywords(text: string): string[] {
+  if (!text) return [];
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(w => w.length > 3);
+}
+
 /**
  * Score and rank all candidates deterministically.
  *

package/src/core/nocturnal-compliance.ts

@@ -513,6 +513,7 @@ function detectT09Opportunity(session: SessionEvents): OpportunityMatch {
  * trigger pattern. Since P_* principles don't have T-xx specific detectors,
  * we use the presence of negative signals as violation evidence.
  */
+    // eslint-disable-next-line complexity -- complexity 14, refactor candidate
 export function detectViolation(principleId: string, session: SessionEvents): ViolationMatch {
   // #216: P_* principles (pain-derived) — generic violation detection
   if (principleId.startsWith('P_')) {

package/src/core/nocturnal-dataset.ts

@@ -645,6 +645,7 @@ export function getDatasetStats(
  * @param targetModelFamily - Default target family for migrated samples
  * @returns Number of newly registered samples
  */
+    // eslint-disable-next-line complexity -- complexity 14, refactor candidate
 export function migrateSampleArtifacts(
   workspaceDir: string,
   targetModelFamily: string | null = null

package/src/core/nocturnal-executability.ts

@@ -278,6 +278,7 @@ function isTooGeneric(text: string): boolean {
  * @param artifact - The validated artifact from arbiter (passed = true)
  * @returns ExecutabilityResult
  */
+    // eslint-disable-next-line complexity -- complexity 14, refactor candidate
 export function validateExecutability(artifact: {
   badDecision: string;
   betterDecision: string;