principles-disciple 1.52.0 → 1.53.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.52.0",
+  "version": "1.53.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/src/core/bootstrap-rules.ts

@@ -13,8 +13,10 @@
  *   npm run bootstrap-rules                               (production)
  */
 
-import { loadLedger, createRule, updatePrinciple } from './principle-tree-ledger.js';
+import { loadLedger, createRule, updatePrinciple, addPrincipleToLedger } from './principle-tree-ledger.js';
+import type { LedgerPrinciple } from './principle-tree-ledger.js';
 import { loadStore } from './principle-training-state.js';
+import { CORE_THINKING_MODELS } from './init.js';
 
 export interface BootstrapResult {
   principleId: string;
@@ -77,12 +79,47 @@ export function selectPrinciplesForBootstrap(stateDir: string, limit = 3): strin
  * @throws Error if no deterministic principles found
  */
 export function bootstrapRules(stateDir: string, limit = 3): BootstrapResult[] {
+  // Migration: if T-01..T-10 exist in Training Store but not in Ledger Tree, backfill.
+  // This handles workspaces initialized before Ledger Tree was added.
+  const store = loadStore(stateDir);
+  const ledger = loadLedger(stateDir);
+  const hasTrainingT = Object.keys(store).some((id) => id.startsWith('T-'));
+  const hasAnyLedgerT = Object.keys(ledger.tree.principles).some((id) => id.startsWith('T-'));
+  if (hasTrainingT && !hasAnyLedgerT) {
+    console.warn('[bootstrap] Migrating T-01..T-10 from Training Store to Ledger Tree');
+    const now = new Date().toISOString();
+    for (const [id, entry] of Object.entries(store)) {
+      if (!id.startsWith('T-')) continue;
+      const model = CORE_THINKING_MODELS.find((m) => m.id === id);
+      if (!model) continue;
+      const lp: LedgerPrinciple = {
+        id,
+        version: 1,
+        text: model.description,
+        coreAxiomId: id,
+        triggerPattern: '',
+        action: '',
+        status: 'active',
+        priority: 'P1',
+        scope: 'general',
+        evaluability: entry.evaluability,
+        valueScore: 0,
+        adherenceRate: 0,
+        painPreventedCount: 0,
+        derivedFromPainIds: [],
+        ruleIds: [],
+        conflictsWithPrincipleIds: [],
+        createdAt: now,
+        updatedAt: now,
+        suggestedRules: [],
+      };
+      addPrincipleToLedger(stateDir, lp);
+    }
+  }
+
   // Select principles for bootstrap
   const selectedPrincipleIds = selectPrinciplesForBootstrap(stateDir, limit);
 
-  // Load current ledger state
-  const ledger = loadLedger(stateDir);
-
   const results: BootstrapResult[] = [];
 
   for (const principleId of selectedPrincipleIds) {

package/src/core/evolution-hook.ts

@@ -0,0 +1,74 @@
+/**
+ * EvolutionHook interface for the Evolution SDK.
+ *
+ * Provides a callback-based interface for observing evolution lifecycle
+ * events: pain detection, principle creation, and principle promotion.
+ *
+ * Per D-03, this interface contains only the 3 core event methods.
+ * Per D-04, consumers implement the interface directly (no EventEmitter).
+ * Hooks not needed can use the provided noOpEvolutionHook and override
+ * individual methods.
+ */
+import type { PainSignal } from './pain-signal.js';
+
+// ---------------------------------------------------------------------------
+// Event Types
+// ---------------------------------------------------------------------------
+
+/** Event payload for principle creation lifecycle events. */
+export interface PrincipleCreatedEvent {
+  /** Unique principle identifier */
+  id: string;
+  /** Principle text ("When X, then Y.") */
+  text: string;
+  /** What triggered this principle's creation */
+  trigger: string;
+}
+
+/** Event payload for principle promotion lifecycle events. */
+export interface PrinciplePromotedEvent {
+  /** Unique principle identifier */
+  id: string;
+  /** Previous status tier */
+  from: string;
+  /** New status tier */
+  to: string;
+}
+
+// ---------------------------------------------------------------------------
+// EvolutionHook Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Callback interface for observing evolution lifecycle events.
+ *
+ * Implement all 3 methods, or spread noOpEvolutionHook and override
+ * only the methods you need:
+ *
+ * @example
+ * ```ts
+ * const myHook: EvolutionHook = {
+ *   ...noOpEvolutionHook,
+ *   onPainDetected(signal) { console.log(signal); },
+ * };
+ * ```
+ */
+export interface EvolutionHook {
+  /** Called when a pain signal is detected and recorded. */
+  onPainDetected(signal: PainSignal): void;
+  /** Called when a new principle candidate is created. */
+  onPrincipleCreated(event: PrincipleCreatedEvent): void;
+  /** Called when a principle is promoted to a higher tier. */
+  onPrinciplePromoted(event: PrinciplePromotedEvent): void;
+}
+
+// ---------------------------------------------------------------------------
+// No-op Helper
+// ---------------------------------------------------------------------------
+
+/** No-op implementation -- consumers can spread and override individual methods. */
+export const noOpEvolutionHook: EvolutionHook = {
+  onPainDetected(_signal: PainSignal): void {},
+  onPrincipleCreated(_event: PrincipleCreatedEvent): void {},
+  onPrinciplePromoted(_event: PrinciplePromotedEvent): void {},
+};

package/src/core/file-storage-adapter.ts

@@ -0,0 +1,203 @@
+/**
+ * FileStorageAdapter — file-backed implementation of StorageAdapter.
+ *
+ * Wraps principle-tree-ledger functions with the async StorageAdapter
+ * contract. Uses withLockAsync for thread-safe mutateLedger with
+ * retry with exponential backoff for lock acquisition (5 retries).
+ * Write failures are logged via SystemLogger and re-thrown.
+ *
+ * Guarantees:
+ * - Atomic writes via atomicWriteFileSync (temp + rename)
+ * - Thread-safe concurrent access via file locks
+ * - Consistent read-after-write visibility
+ * - Write failures logged to SystemLogger and re-thrown
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import type { StorageAdapter } from './storage-adapter.js';
+import type { HybridLedgerStore } from './principle-tree-ledger.js';
+import { TREE_NAMESPACE } from './principle-tree-ledger.js';
+import {
+  loadLedger as loadLedgerFromFile,
+  saveLedgerAsync,
+} from './principle-tree-ledger.js';
+import { withLockAsync, type LockOptions, LockAcquisitionError } from '../utils/file-lock.js';
+import { atomicWriteFileSync } from '../utils/io.js';
+import { SystemLogger } from './system-logger.js';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Maximum retries for lock acquisition in mutateLedger. */
+const MUTATE_RETRY_COUNT = 5;
+
+/** Base delay in ms for exponential backoff between retries. */
+const MUTATE_BACKOFF_BASE_MS = 50;
+
+/** Maximum backoff delay in ms. */
+const MUTATE_BACKOFF_MAX_MS = 500;
+
+const PRINCIPLE_TRAINING_FILE = 'principle_training_state.json';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize the hybrid ledger store to JSON.
+ * Mirrors the unexported serializeLedger from principle-tree-ledger.ts.
+ */
+function serializeStore(store: HybridLedgerStore): string {
+  return JSON.stringify(
+    {
+      ...store.trainingStore,
+      [TREE_NAMESPACE]: {
+        ...store.tree,
+        lastUpdated: new Date().toISOString(),
+      },
+    },
+    null,
+    2,
+  );
+}
+
+/** Ensure the parent directory exists before writing. */
+function ensureParentDir(filePath: string): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// FileStorageAdapter
+// ---------------------------------------------------------------------------
+
+/**
+ * File-system backed storage adapter for the principle ledger.
+ *
+ * Delegates read/write operations to principle-tree-ledger while providing
+ * the async StorageAdapter interface. The mutateLedger method uses
+ * withLockAsync with exponential backoff retry for robust concurrent access.
+ */
+export class FileStorageAdapter implements StorageAdapter {
+  private readonly stateDir: string;
+  private readonly workspaceDir: string | undefined;
+
+  constructor(stateDir: string, workspaceDir?: string) {
+    this.stateDir = stateDir;
+    this.workspaceDir = workspaceDir;
+  }
+
+  /** Resolve the ledger file path for this state directory. */
+  private get filePath(): string {
+    return path.join(this.stateDir, PRINCIPLE_TRAINING_FILE);
+  }
+
+  /**
+   * Load the current ledger state from the file system.
+   *
+   * Returns an empty store if no persisted state exists (first run).
+   * Uses the synchronous loadLedger from principle-tree-ledger which
+   * handles missing/corrupted files gracefully.
+   */
+  async loadLedger(): Promise<HybridLedgerStore> {
+    return loadLedgerFromFile(this.stateDir);
+  }
+
+  /**
+   * Persist the full ledger state atomically.
+   *
+   * Delegates to principle-tree-ledger's saveLedgerAsync which uses
+   * withLockAsync internally. Logs failures via SystemLogger.
+   */
+  async saveLedger(store: HybridLedgerStore): Promise<void> {
+    try {
+      await saveLedgerAsync(this.stateDir, store);
+    } catch (err) {
+      SystemLogger.log(
+        this.workspaceDir,
+        'STORAGE_WRITE_FAILED',
+        `FileStorageAdapter.saveLedger failed: ${String(err)}`,
+      );
+      throw err;
+    }
+  }
+
+  /**
+   * Perform a read-modify-write cycle with automatic locking and retry.
+   *
+   * Uses withLockAsync to acquire a file lock, reads the current store,
+   * applies the mutate function, then writes the modified store atomically.
+   * On lock acquisition failure, retries up to MUTATE_RETRY_COUNT (5) times
+   * with exponential backoff + jitter to reduce contention.
+   *
+   * Write failures are logged to SystemLogger and re-thrown so callers
+   * can decide how to handle persistence errors.
+   */
+  async mutateLedger<T>(mutate: (store: HybridLedgerStore) => T | Promise<T>): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < MUTATE_RETRY_COUNT; attempt++) {
+      try {
+        const lockOptions: LockOptions = {
+          maxRetries: 3,
+          baseRetryDelayMs: 10,
+          maxRetryDelayMs: 200,
+          lockStaleMs: 10_000,
+        };
+
+        const ledgerPath = this.filePath;
+
+        return await withLockAsync(ledgerPath, async () => {
+          const store = loadLedgerFromFile(this.stateDir);
+          const result = await mutate(store);
+
+          // Write directly — we already hold the lock, so we must NOT
+          // call saveLedger/saveLedgerAsync (they try to acquire the same lock).
+          try {
+            ensureParentDir(ledgerPath);
+            atomicWriteFileSync(ledgerPath, serializeStore(store));
+          } catch (writeErr) {
+            SystemLogger.log(
+              this.workspaceDir,
+              'STORAGE_WRITE_FAILED',
+              `FileStorageAdapter.mutateLedger write failed: ${String(writeErr)}`,
+            );
+            throw writeErr;
+          }
+
+          return result;
+        }, lockOptions);
+      } catch (err) {
+        lastError = err as Error;
+
+        // Only retry on lock acquisition errors
+        if (err instanceof LockAcquisitionError && attempt < MUTATE_RETRY_COUNT - 1) {
+          const delay = Math.min(
+            MUTATE_BACKOFF_BASE_MS * Math.pow(2, attempt),
+            MUTATE_BACKOFF_MAX_MS,
+          );
+          // Add jitter (0-20%) to avoid thundering herd
+          const jitter = delay * 0.2 * Math.random();
+          const totalDelay = Math.floor(delay + jitter);
+
+          await new Promise((resolve) => setTimeout(resolve, totalDelay));
+          continue;
+        }
+
+        // Non-retryable error or exhausted retries
+        SystemLogger.log(
+          this.workspaceDir,
+          'STORAGE_MUTATE_FAILED',
+          `FileStorageAdapter.mutateLedger failed after ${attempt + 1} attempts: ${String(err)}`,
+        );
+        throw err;
+      }
+    }
+
+    // Should not reach here, but satisfy the type checker
+    throw lastError ?? new Error('FileStorageAdapter.mutateLedger: unexpected state');
+  }
+}

package/src/core/init.ts

@@ -5,6 +5,8 @@ import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
 import { PD_DIRS } from './paths.js';
 import { defaultContextConfig } from '../types.js';
 import { loadStore, setPrincipleState, type PrincipleTrainingState } from './principle-training-state.js';
+import { addPrincipleToLedger } from './principle-tree-ledger.js';
+import type { LedgerPrinciple } from './principle-tree-ledger.js';
 import { atomicWriteFileSync } from '../utils/io.js';
 import { createDefaultKeywordStore, saveKeywordStore } from './empathy-keyword-matcher.js';
 
@@ -150,7 +152,7 @@ function copyRecursiveSync(srcDir: string, destDir: string, api: OpenClawPluginA
  * Core thinking model definitions (T-01 through T-10).
  * These are the built-in cognitive patterns that every workspace should have.
  */
-const CORE_THINKING_MODELS: Array<{
+export const CORE_THINKING_MODELS: Array<{
   id: string;
   name: string;
   description: string;
@@ -190,7 +192,7 @@ export function ensureCorePrinciples(stateDir: string, logger: PluginLogger): bo
     for (const model of CORE_THINKING_MODELS) {
       const state: PrincipleTrainingState = {
         principleId: model.id,
-        evaluability: 'deterministic',
+        evaluability: 'manual_only',
         applicableOpportunityCount: 0,
         observedViolationCount: 0,
         complianceRate: 0,
@@ -202,6 +204,31 @@ export function ensureCorePrinciples(stateDir: string, logger: PluginLogger): bo
         internalizationStatus: 'needs_training',
       };
       setPrincipleState(stateDir, state);
+
+      // Also write to Ledger Tree so bootstrapRules() can find them
+      const now = new Date().toISOString();
+      const ledgerPrinciple: LedgerPrinciple = {
+        id: model.id,
+        version: 1,
+        text: model.description,
+        coreAxiomId: model.id,
+        triggerPattern: '',
+        action: '',
+        status: 'active',
+        priority: 'P1',
+        scope: 'general',
+        evaluability: 'manual_only',
+        valueScore: 0,
+        adherenceRate: 0,
+        painPreventedCount: 0,
+        derivedFromPainIds: [],
+        ruleIds: [],
+        conflictsWithPrincipleIds: [],
+        createdAt: now,
+        updatedAt: now,
+        suggestedRules: [],
+      };
+      addPrincipleToLedger(stateDir, ledgerPrinciple);
     }
 
     logger.info(`[PD] Initialized ${CORE_THINKING_MODELS.length} core thinking models: T-01 through T-10`);

package/src/core/nocturnal-trinity.ts

@@ -2211,6 +2211,20 @@ export async function runTrinityAsync(options: RunTrinityOptions): Promise<Trini
       telemetry.eligibleCandidateCount = draftArtifact.telemetry.eligibleCandidateCount;
     }
 
+    // Hallucination detection (SDK-QUAL-02): validate extraction against snapshot
+    const hallucinationResult = validateExtraction(draftArtifact, snapshot);
+    if (!hallucinationResult.isGrounded) {
+      const reason = hallucinationResult.reason ?? 'Extraction not grounded in session evidence';
+      console.warn(`[Trinity] HALLUCINATION_DETECTED: ${reason}`);
+      telemetry.stageFailures.push(`Hallucination: ${reason}`);
+      return {
+        success: false,
+        telemetry,
+        failures: [{ stage: 'scribe', reason }],
+        fallbackOccurred: false,
+      };
+    }
+
     return {
       success: true,
       artifact: draftArtifact,
@@ -2339,6 +2353,20 @@ function runTrinityWithStubs(
     telemetry.eligibleCandidateCount = draftArtifact.telemetry.eligibleCandidateCount;
   }
 
+  // Hallucination detection (SDK-QUAL-02): validate extraction against snapshot
+  const hallucinationResult = validateExtraction(draftArtifact, snapshot);
+  if (!hallucinationResult.isGrounded) {
+    const reason = hallucinationResult.reason ?? 'Extraction not grounded in session evidence';
+    console.warn(`[Trinity] HALLUCINATION_DETECTED: ${reason}`);
+    telemetry.stageFailures.push(`Hallucination: ${reason}`);
+    return {
+      success: false,
+      telemetry,
+      failures: [{ stage: 'scribe', reason }],
+      fallbackOccurred: false,
+    };
+  }
+
   return {
     success: true,
     artifact: draftArtifact,
@@ -2405,6 +2433,208 @@ export function validateDraftArtifact(draft: TrinityDraftArtifact): DraftValidat
   };
 }
 
+// ---------------------------------------------------------------------------
+// Hallucination Detection (SDK-QUAL-02)
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of hallucination validation against session snapshot evidence.
+ */
+export interface HallucinationDetectionResult {
+  /** Whether the extraction is grounded in real session evidence */
+  isGrounded: boolean;
+  /** List of evidence types found in the snapshot supporting the extraction */
+  evidenceTypes: string[];
+  /** Detailed reason if hallucination is detected */
+  reason?: string;
+  /** Matching evidence items for telemetry (truncated for safety) */
+  evidencePreview: string[];
+}
+
+/**
+ * Validate that an extracted badDecision corresponds to actual events in the
+ * NocturnalSessionSnapshot. This catches hallucinated extractions where the
+ * Trinity chain produces a badDecision that has no grounding in real failures,
+ * pain events, or gate blocks.
+ *
+ * Evidence sources checked:
+ *  1. Failed tool calls (snapshot.toolCalls with outcome='failure')
+ *  2. Pain events (snapshot.painEvents with score >= 50)
+ *  3. Gate blocks (snapshot.gateBlocks)
+ *  4. User corrections (snapshot.userTurns with correctionDetected=true)
+ *
+ * The function uses keyword overlap heuristics: it extracts tool names, file
+ * paths, error messages, and pain reasons from the snapshot and checks if the
+ * badDecision text overlaps meaningfully with any of them.
+ *
+ * @param artifact The draft artifact produced by the Scribe stage
+ * @param snapshot The session snapshot used to generate the extraction
+ * @returns HallucinationDetectionResult indicating whether the extraction is grounded
+ */
+export function validateExtraction(
+  artifact: TrinityDraftArtifact,
+  snapshot: NocturnalSessionSnapshot
+): HallucinationDetectionResult {
+  const evidenceTypes: string[] = [];
+  const evidencePreview: string[] = [];
+
+  // Shared token normalizer: lowercase + strip punctuation, same as badDecisionTokens
+  const normalizeEvidenceToken = (value: string): string =>
+    value.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+  // Build a set of evidence tokens from the snapshot
+  const evidenceTokens = new Set<string>();
+  const badDecisionLower = artifact.badDecision.toLowerCase();
+
+  // 1. Failed tool calls
+  const failedToolCalls = (snapshot.toolCalls ?? []).filter(tc => tc.outcome === 'failure');
+  if (failedToolCalls.length > 0) {
+    evidenceTypes.push('tool_failures');
+    for (const tc of failedToolCalls) {
+      // Extract tool name tokens
+      evidenceTokens.add(tc.toolName.toLowerCase());
+      if (tc.filePath) {
+        // Extract all path segments and normalize each for matching
+        const rawPathParts = [tc.filePath, ...tc.filePath.split(/[\\/]/)];
+        for (const part of rawPathParts) {
+          const normalized = normalizeEvidenceToken(part);
+          if (normalized.length > 0) evidenceTokens.add(normalized);
+        }
+      }
+      if (tc.errorMessage) {
+        // Extract key words from error messages (filter stop words)
+        const errorWords = tc.errorMessage.toLowerCase().split(/\s+/)
+          .filter(w => w.length > 3 && !['with', 'from', 'that', 'this', 'which', 'been', 'have', 'were', 'they', 'their'].includes(w));
+        for (const w of errorWords) {
+          const normalized = normalizeEvidenceToken(w);
+          if (normalized.length > 0) evidenceTokens.add(normalized);
+        }
+      }
+      if (tc.errorType) evidenceTokens.add(tc.errorType.toLowerCase());
+      evidencePreview.push(`tool:${tc.toolName}${tc.filePath ? `@${tc.filePath}` : ''} -> ${tc.errorMessage ?? 'unknown'}`.slice(0, 100));
+    }
+  }
+
+  // 2. Pain events (score >= 50 indicates meaningful pain)
+  const significantPainEvents = (snapshot.painEvents ?? []).filter(pe => pe.score >= 50);
+  if (significantPainEvents.length > 0) {
+    evidenceTypes.push('pain_events');
+    for (const pe of significantPainEvents) {
+      evidenceTokens.add(pe.source.toLowerCase());
+      if (pe.reason) {
+        const painWords = pe.reason.toLowerCase().split(/\s+/)
+          .filter(w => w.length > 3 && !['with', 'from', 'that', 'this', 'which', 'been', 'have', 'were', 'they', 'their'].includes(w));
+        for (const w of painWords) {
+          const normalized = normalizeEvidenceToken(w);
+          if (normalized.length > 0) evidenceTokens.add(normalized);
+        }
+      }
+      evidencePreview.push(`pain:${pe.score} [${pe.source}] ${pe.reason ?? ''}`.slice(0, 100));
+    }
+  }
+
+  // 3. Gate blocks
+  if ((snapshot.gateBlocks ?? []).length > 0) {
+    evidenceTypes.push('gate_blocks');
+    for (const gb of snapshot.gateBlocks) {
+      evidenceTokens.add(gb.toolName.toLowerCase());
+      evidenceTokens.add('gate');
+      evidenceTokens.add('blocked');
+      if (gb.reason) {
+        const blockWords = gb.reason.toLowerCase().split(/\s+/)
+          .filter(w => w.length > 3);
+        for (const w of blockWords) {
+          const normalized = normalizeEvidenceToken(w);
+          if (normalized.length > 0) evidenceTokens.add(normalized);
+        }
+      }
+      evidencePreview.push(`gate:${gb.toolName} -> ${gb.reason}`.slice(0, 100));
+    }
+  }
+
+  // 4. User corrections
+  const userCorrections = (snapshot.userTurns ?? []).filter(ut => ut.correctionDetected);
+  if (userCorrections.length > 0) {
+    evidenceTypes.push('user_corrections');
+    evidenceTokens.add('correction');
+    evidenceTokens.add('wrong');
+    evidenceTokens.add('incorrect');
+    evidencePreview.push(`corrections:${userCorrections.length}`);
+  }
+
+  // If no evidence exists at all in the snapshot, we cannot validate.
+  // Allow the extraction through — the pipeline already has guardrails for
+  // empty snapshots (Dreamer returns valid:false).
+  if (evidenceTypes.length === 0) {
+    return {
+      isGrounded: true,
+      evidenceTypes: [],
+      reason: undefined,
+      evidencePreview: [],
+    };
+  }
+
+  // Check for overlap between badDecision text and evidence tokens
+  // We look for meaningful keyword matches (tokens of length > 4)
+  const badDecisionTokens = badDecisionLower.split(/\s+/)
+    .map(t => t.replace(/[^a-z0-9]/g, ''))
+    .filter(t => t.length > 4);
+
+  let matchCount = 0;
+  const matchedTokens: string[] = [];
+  for (const token of badDecisionTokens) {
+    // Direct match
+    if (evidenceTokens.has(token)) {
+      matchCount++;
+      matchedTokens.push(token);
+      continue;
+    }
+    // Partial match: check if any evidence token contains this token or vice versa
+    for (const evToken of evidenceTokens) {
+      if (evToken.length > 4 && (evToken.includes(token) || token.includes(evToken))) {
+        matchCount++;
+        matchedTokens.push(token);
+        break;
+      }
+    }
+  }
+
+  // Heuristic: if at least 2 meaningful tokens overlap, consider grounded
+  // Single overlap is acceptable if the token is highly specific (length > 8)
+  const minOverlap = badDecisionTokens.length > 0
+    ? Math.max(1, Math.ceil(badDecisionTokens.length * 0.15))
+    : 0;
+
+  if (matchCount >= Math.max(2, minOverlap)) {
+    return {
+      isGrounded: true,
+      evidenceTypes,
+      evidencePreview: evidencePreview.slice(0, 5),
+    };
+  }
+
+  // Also check for at least one highly-specific match (length > 8)
+  const hasHighlySpecificMatch = matchedTokens.some(t => t.length > 8);
+  if (hasHighlySpecificMatch) {
+    return {
+      isGrounded: true,
+      evidenceTypes,
+      evidencePreview: evidencePreview.slice(0, 5),
+    };
+  }
+
+  // Hallucination detected — badDecision has no grounding in snapshot evidence
+  const reason = `Hallucinated extraction: badDecision "${artifact.badDecision.slice(0, 80)}" has insufficient overlap with session evidence. ` +
+    `Evidence types available: [${evidenceTypes.join(', ')}]. Matched tokens: [${matchedTokens.join(', ')}] (needed >= ${Math.max(2, minOverlap)}).`;
+
+  return {
+    isGrounded: false,
+    evidenceTypes,
+    reason,
+    evidencePreview: evidencePreview.slice(0, 5),
+  };
+}
+
 /**
  * Convert a TrinityDraftArtifact to a NocturnalArtifact-compatible structure.
  */