principles-disciple 1.8.3 → 1.9.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.8.3",
+  "version": "1.9.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/src/core/pain-context-extractor.ts

@@ -0,0 +1,286 @@
+/**
+ * Pain Context Extractor
+ *
+ * Extracts conversation context from OpenClaw session JSONL files
+ * to provide diagnostic context beyond the pain reason.
+ *
+ * DESIGN PRINCIPLES (from real data analysis):
+ * - JSONL files can be 6 lines (HEARTBEAT injection) to 632+ lines (full conversation)
+ * - Large files: one line can be 11MB (system prompt) — MUST skip oversized lines
+ * - Assistant text appears ONLY in final replies (~3% of assistant messages)
+ * - Most assistant messages contain toolCall blocks (what operations were performed)
+ * - toolResult contains tool output (success AND failure) — both are useful for diagnosis
+ * - Always read from END of file to get most recent context
+ *
+ * SAFETY:
+ * - Never load entire file (tail-only, max 512KB)
+ * - Skip lines > 100KB (real files have 11MB single lines)
+ * - Cap total output at 1500 chars
+ * - All errors caught silently — return empty string on failure
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// =========================================================================
+// Safety Limits
+// =========================================================================
+
+/** Skip JSONL lines larger than this */
+const MAX_LINE_BYTES = 100_000; // 100KB
+/** Only read last portion of file */
+const TAIL_READ_SIZE = 512_000; // 512KB
+/** Max turns to extract */
+const MAX_TURNS = 8;
+/** Max chars per turn entry */
+const MAX_TURN_CHARS = 250;
+/** Max total output */
+const MAX_OUTPUT_CHARS = 1500;
+
+/** Valid characters for session IDs and agent IDs — prevents path traversal */
+const SAFE_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
+
+function getAgentsDir(): string {
+  return process.env.PD_TEST_AGENTS_DIR || path.join(os.homedir(), '.openclaw', 'agents');
+}
+
+// =========================================================================
+// Safe File Reading
+// =========================================================================
+
+function safeTail(filePath: string): string[] {
+  try {
+    if (!fs.existsSync(filePath)) return [];
+    const stat = fs.statSync(filePath);
+    if (stat.size === 0) return [];
+
+    const isTruncated = stat.size > TAIL_READ_SIZE;
+    const readSize = Math.min(stat.size, TAIL_READ_SIZE);
+    const buffer = Buffer.alloc(readSize);
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      fs.readSync(fd, buffer, 0, readSize, stat.size - readSize);
+      const content = buffer.toString('utf8');
+      // Only strip first line if file was actually truncated (started mid-line)
+      const validContent = isTruncated ? content.slice(content.indexOf('\n') + 1) : content;
+      return validContent.split('\n').filter(l => l.trim().length > 0);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (err) {
+    console.debug(`[pain-context-extractor] safeTail failed: ${String(err)}`);
+    return [];
+  }
+}
+
+// =========================================================================
+// Safe JSONL Parsing
+// =========================================================================
+
+interface ParsedMessage {
+  role: string;
+  textParts: string[];
+  toolCalls: Array<{ id?: string; name?: string; arguments?: Record<string, unknown> }>;
+  toolCallId?: string;
+  toolName?: string;
+  details?: { exitCode?: number; isError?: boolean; aggregated?: string };
+}
+
+function parseSafeMessages(lines: string[]): ParsedMessage[] {
+  const messages: ParsedMessage[] = [];
+  for (const line of lines) {
+    if (line.length > MAX_LINE_BYTES) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed.type !== 'message' || !parsed.message) continue;
+      const msg = parsed.message;
+      const content = Array.isArray(msg.content) ? msg.content : [];
+      messages.push({
+        role: msg.role || '',
+        textParts: content.filter((c: { type: string }) => c.type === 'text').map((c: { text?: string }) => c.text || ''),
+        toolCalls: content.filter((c: { type: string }) => c.type === 'toolCall').map((c: { id?: string; name?: string; arguments?: Record<string, unknown> }) => ({ id: c.id, name: c.name, arguments: c.arguments })),
+        toolCallId: msg.toolCallId,
+        toolName: msg.toolName,
+        details: msg.details,
+      });
+    } catch { /* malformed JSON line, skip silently — expected with corrupted files */ }
+  }
+  return messages;
+}
+
+// =========================================================================
+// Turn Extraction
+// =========================================================================
+
+/**
+ * Extracts a concise turn representation from a message.
+ * Returns null if nothing useful to extract.
+ */
+function extractTurn(msg: ParsedMessage): string | null {
+  if (msg.role === 'user' && msg.textParts.length > 0) {
+    // For user messages, skip system prompt injection patterns
+    const text = msg.textParts.join(' ').trim();
+    if (!text) return null;
+    // Skip if it looks like a system injection
+    if (text.startsWith('<evolution_task') || text.startsWith('<system_override') ||
+        text.startsWith('You are an empathy observer') || text.startsWith('Analyze ONLY') ||
+        text.startsWith('{"damageDetected"')) return null;
+    // Find the last meaningful user input line
+    const lines = text.split('\n');
+    let lastInput = '';
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.length > 3 && trimmed.length < 500 &&
+          !trimmed.startsWith('<') && !trimmed.startsWith('{') &&
+          !trimmed.startsWith('Trust Score:') && !trimmed.startsWith('Hygiene:')) {
+        lastInput = trimmed;
+      }
+    }
+    const userInput = lastInput || text;
+    return `[User]: ${userInput.substring(0, MAX_TURN_CHARS)}`;
+  }
+
+  if (msg.role === 'assistant') {
+    // Priority 1: final text reply
+    if (msg.textParts.length > 0) {
+      const text = msg.textParts.join(' ').trim();
+      if (text) return `[Assistant]: ${text.substring(0, MAX_TURN_CHARS)}`;
+    }
+    // Priority 2: tool call summary (what operations were performed)
+    if (msg.toolCalls.length > 0) {
+      const tools = msg.toolCalls.map(tc => tc.name).filter(Boolean);
+      const uniqueTools = [...new Set(tools)];
+      if (uniqueTools.length > 0) {
+        return `[Assistant → ${uniqueTools.join(', ')}]`;
+      }
+    }
+  }
+
+  if (msg.role === 'toolResult') {
+    const exitCode = msg.details?.exitCode;
+    const isError = msg.details?.isError || (exitCode !== undefined && exitCode !== 0);
+    const text = msg.textParts.join(' ').trim();
+    const toolLabel = msg.toolName || 'tool';
+
+    if (isError) {
+      // Failed tool call — important for diagnosis
+      const errorPreview = text ? text.substring(0, MAX_TURN_CHARS) : `(exit ${exitCode ?? '?'})`;
+      return `[${toolLabel} FAILED]: ${errorPreview}`;
+    }
+
+    // Successful tool call — include brief result
+    if (text) {
+      // For successful results, show first meaningful line
+      const lines = text.split('\n').filter(l => l.trim());
+      const firstLine = lines[0]?.substring(0, MAX_TURN_CHARS) || '';
+      if (firstLine) return `[${toolLabel}]: ${firstLine}`;
+    }
+  }
+
+  return null;
+}
+
+// =========================================================================
+// Public API
+// =========================================================================
+
+/**
+ * Extracts recent conversation context from a session's JSONL file.
+ *
+ * SAFETY: Tail-only read, skip oversized lines, cap output.
+ * Returns empty string on any failure — caller should use pain reason as fallback.
+ */
+export async function extractRecentConversation(
+  sessionId: string,
+  agentId: string = 'main',
+  maxTurns: number = MAX_TURNS,
+): Promise<string> {
+  if (!sessionId || sessionId.length < 5 || !SAFE_ID_REGEX.test(sessionId)) return '';
+  if (agentId && !SAFE_ID_REGEX.test(agentId)) return '';
+  try {
+    const jsonlPath = path.join(getAgentsDir(), agentId, 'sessions', `${sessionId}.jsonl`);
+    const lines = safeTail(jsonlPath);
+    const messages = parseSafeMessages(lines);
+    if (messages.length === 0) return '';
+
+    const turns: string[] = [];
+    for (const msg of messages) {
+      const turn = extractTurn(msg);
+      if (turn) turns.push(turn);
+    }
+
+    const recent = turns.slice(-maxTurns);
+    if (recent.length === 0) return '';
+    const result = recent.join('\n');
+    return result.length > MAX_OUTPUT_CHARS ? result.substring(0, MAX_OUTPUT_CHARS - 3) + '...' : result;
+  } catch (err) {
+    console.debug(`[pain-context-extractor] extractRecentConversation failed for session=${sessionId}, agent=${agentId}: ${String(err)}`);
+    return ''; // Fail silently
+  }
+}
+
+/**
+ * Extracts failed tool call context with argument correlation.
+ */
+export async function extractFailedToolContext(
+  sessionId: string,
+  agentId: string = 'main',
+  toolName: string,
+  filePath?: string,
+): Promise<string> {
+  if (!sessionId || sessionId.length < 5 || !SAFE_ID_REGEX.test(sessionId) || !toolName) return '';
+  if (agentId && !SAFE_ID_REGEX.test(agentId)) return '';
+  try {
+    const jsonlPath = path.join(getAgentsDir(), agentId, 'sessions', `${sessionId}.jsonl`);
+    const lines = safeTail(jsonlPath);
+    const messages = parseSafeMessages(lines);
+    if (messages.length === 0) return '';
+
+    // Build toolCallId → arguments map
+    // Keep both full args (for matching) and truncated (for display)
+    const toolArgsById = new Map<string, { name: string; fullArgs: string; previewArgs: string }>();
+    for (const msg of messages) {
+      for (const tc of msg.toolCalls) {
+        if (tc.id && tc.name) {
+          const args = tc.arguments || {};
+          const fullArgs = JSON.stringify(args);
+          const truncated: Record<string, unknown> = {};
+          for (const [k, v] of Object.entries(args)) {
+            const s = typeof v === 'string' ? v : JSON.stringify(v);
+            truncated[k] = s.length > 150 ? s.substring(0, 150) + '...' : s;
+          }
+          toolArgsById.set(tc.id, {
+            name: tc.name,
+            fullArgs,
+            previewArgs: JSON.stringify(truncated, null, 2),
+          });
+        }
+      }
+    }
+
+    const parts: string[] = [];
+    for (const msg of messages) {
+      if (msg.role === 'toolResult' && msg.toolName === toolName) {
+        const exitCode = msg.details?.exitCode;
+        const isError = msg.details?.isError || (exitCode !== undefined && exitCode !== 0);
+        if (!isError) continue;
+
+        const toolCallId = msg.toolCallId;
+        const correlated = toolCallId ? toolArgsById.get(toolCallId) : null;
+        if (filePath && correlated && !correlated.fullArgs.includes(filePath)) continue;
+
+        parts.push(`[Tool Call: ${correlated?.name || toolName}]`);
+        if (correlated) parts.push(`Arguments: ${correlated.previewArgs.substring(0, 300)}`);
+        parts.push(`Exit Code: ${exitCode ?? 'N/A'}`);
+        const errorText = msg.textParts.join(' ').trim();
+        if (errorText) parts.push(`Error: ${errorText.substring(0, 500)}`);
+        break;
+      }
+    }
+    return parts.length > 0 ? parts.join('\n') : '';
+  } catch (err) {
+    console.debug(`[pain-context-extractor] extractFailedToolContext failed for tool=${toolName}, session=${sessionId}: ${String(err)}`);
+    return '';
+  }
+}

package/src/core/pain.ts

@@ -4,6 +4,88 @@ import { serializeKvLines, parseKvLines } from '../utils/io.js';
 import { resolvePdPath } from './paths.js';
 import { ConfigService } from './config-service.js';
 
+// =========================================================================
+// Pain Flag Contract (Single Source of Truth)
+//
+// All pain flag writers MUST use buildPainFlag() below.
+// If you need to add a new field, update this type AND buildPainFlag().
+// This prevents format drift across the 5+ pain signal sources.
+// =========================================================================
+
+/**
+ * Required fields — every pain flag MUST have these.
+ */
+export interface PainFlagData {
+  /** What triggered this pain signal (e.g., tool_failure, human_intervention, intercept_extraction) */
+  source: string;
+  /** Pain score 0-100 */
+  score: string;
+  /** ISO 8601 timestamp */
+  time: string;
+  /** Human-readable reason / error description */
+  reason: string;
+  /** Session ID — identifies which conversation this happened in */
+  session_id: string;
+  /** Agent ID — identifies which agent (main, builder, diagnostician, etc.) */
+  agent_id: string;
+  /** 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;
+}
+
+/**
+ * Factory function — the ONLY way to construct pain flag data.
+ *
+ * All callers (hooks/pain.ts, hooks/subagent.ts, hooks/lifecycle.ts,
+ * hooks/llm.ts, skills/pain/SKILL.md) must go through this function.
+ *
+ * Required fields are enforced by TypeScript — you can't compile
+ * without providing source, score, time, reason, session_id, agent_id.
+ *
+ * Optional fields (trace_id, trigger_text_preview) default to empty string.
+ */
+export function buildPainFlag(input: {
+  source: string;
+  score: string;
+  time?: string;
+  reason: string;
+  session_id?: string;
+  agent_id?: string;
+  is_risky?: boolean;
+  trace_id?: string;
+  trigger_text_preview?: string;
+}): PainFlagData {
+  return {
+    source: input.source,
+    score: input.score,
+    time: input.time || new Date().toISOString(),
+    reason: input.reason,
+    session_id: input.session_id || '',
+    agent_id: input.agent_id || '',
+    is_risky: input.is_risky ? 'true' : 'false',
+    trace_id: input.trace_id || '',
+    trigger_text_preview: input.trigger_text_preview || '',
+  };
+}
+
+/**
+ * Validates a pain flag read from disk.
+ * Returns list of missing required fields — empty string means all present.
+ */
+export function validatePainFlag(data: Record<string, string>): string[] {
+  const missing: string[] = [];
+  const required = ['source', 'score', 'time', 'reason', 'session_id', 'agent_id'] as const;
+  for (const field of required) {
+    if (!data[field] || data[field].trim() === '') {
+      missing.push(field);
+    }
+  }
+  return missing;
+}
+
 export function computePainScore(rc: number, isSpiral: boolean, missingTestCommand: boolean, softScore: number, projectDir?: string): number {
   let score = Math.max(0, softScore || 0);
   
@@ -54,7 +136,7 @@ export function painSeverityLabel(painScore: number, isSpiral: boolean = false,
   }
 }
 
-export function writePainFlag(projectDir: string, painData: Record<string, string>): void {
+export function writePainFlag(projectDir: string, painData: PainFlagData): void {
   const painFlagPath = resolvePdPath(projectDir, 'PAIN_FLAG');
   const dir = path.dirname(painFlagPath);
   if (!fs.existsSync(dir)) {

package/src/hooks/lifecycle.ts

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
-import { computePainScore, writePainFlag } from '../core/pain.js';
+import { computePainScore, buildPainFlag, writePainFlag } from '../core/pain.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { PD_DIRS } from '../core/paths.js';
 import { 
@@ -154,14 +154,15 @@ export async function extractPainFromSessionFile(sessionFile: string, ctx: Plugi
 
       const hasFatal = painPoints.some(p => p.includes('[FATAL INTERCEPT]'));
       if (hasFatal) {
-        writePainFlag(workspaceDir, {
+        writePainFlag(workspaceDir, buildPainFlag({
           source: 'intercept_extraction',
           score: '100',
-          time: new Date().toISOString(),
           reason: 'Hard intercept detected in session history compaction.',
-          is_risky: 'true',
-          trigger_text_preview: painPoints.find(p => p.includes('[FATAL INTERCEPT]'))?.substring(0, 150) || 'Fatal intercept'
-        });
+          is_risky: true,
+          trigger_text_preview: painPoints.find(p => p.includes('[FATAL INTERCEPT]'))?.substring(0, 150) || 'Fatal intercept',
+          session_id: ctx.sessionId || '',
+          agent_id: ctx.agentId || '',
+        }));
       }
     } catch (err) {
       ctx.logger?.error?.(`[PD:Lifecycle] Failed to write pain signals: ${String(err)}`);

package/src/hooks/llm.ts

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { PluginHookLlmOutputEvent, PluginHookAgentContext } from '../openclaw-sdk.js';
 import { trackFriction, trackLlmOutput, recordThinkingCheckpoint, resetFriction } from '../core/session-tracker.js';
-import { writePainFlag } from '../core/pain.js';
+import { buildPainFlag, writePainFlag } from '../core/pain.js';
 import { ControlUiDatabase } from '../core/control-ui-db.js';
 import { DetectionService } from '../core/detection-service.js';
 import { detectThinkingModelMatches, deriveThinkingScenarios } from '../core/thinking-models.js';
@@ -326,14 +326,15 @@ export function handleLlmOutput(
         const snippet = text.length > 200 ? text.substring(0, 100) + '...' + text.substring(text.length - 100) : text;
 
         try {
-            writePainFlag(ctx.workspaceDir, {
+            writePainFlag(ctx.workspaceDir, buildPainFlag({
                 source,
                 score: String(painScore),
-                time: new Date().toISOString(),
                 reason: matchedReason,
-                is_risky: 'false',
-                trigger_text_preview: snippet
-            });
+                is_risky: false,
+                trigger_text_preview: snippet,
+                session_id: ctx.sessionId || '',
+                agent_id: ctx.agentId || '',
+            }));
         } catch (e) {
             ctx.logger?.warn?.(`[PD:LLM] Failed to write pain flag: ${String(e)}`);
         }

package/src/hooks/pain.ts

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { isRisky, normalizePath } from '../utils/io.js';
 import { normalizeProfile } from '../core/profile.js';
-import { computePainScore, writePainFlag, trackPrincipleValue } from '../core/pain.js';
+import { computePainScore, buildPainFlag, writePainFlag, trackPrincipleValue } from '../core/pain.js';
 import { getSession, trackFriction, resetFriction, getInjectedProbationIds, clearInjectedProbationIds } from '../core/session-tracker.js';
 import { denoiseError, computeHash } from '../utils/hashing.js';
 import { SystemLogger } from '../core/system-logger.js';
@@ -273,16 +273,15 @@ export function handleAfterToolCall(
   const painScore = computePainScore(1, false, false, isRisk ? 20 : 0, effectiveWorkspaceDir);
   const traceId = createTraceId();
 
-  const painData = {
-    score: String(painScore),
+  const painData = buildPainFlag({
     source: 'tool_failure',
-    time: new Date().toISOString(),
+    score: String(painScore),
     reason: `Tool ${event.toolName} failed on ${relPath}. Error: ${event.error ?? 'Non-zero exit code'}`,
-    is_risky: String(isRisk),
+    is_risky: isRisk,
     trace_id: traceId,
     session_id: sessionId,
     agent_id: ctx.agentId || '',
-  };
+  });
 
   try {
     writePainFlag(effectiveWorkspaceDir, painData);

package/src/hooks/subagent.ts

@@ -1,6 +1,6 @@
 import type { PluginHookSubagentEndedEvent, PluginHookSubagentContext, PluginLogger, OpenClawPluginApi } from '../openclaw-sdk.js';
 import * as fs from 'fs';
-import { writePainFlag } from '../core/pain.js';
+import { buildPainFlag, writePainFlag } from '../core/pain.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 // No longer needed — diagnostician runs via HEARTBEAT, not subagent
 import { recordEvolutionSuccess } from '../core/evolution-engine.js';
@@ -163,15 +163,14 @@ export async function handleSubagentEnded(
         const score = scoreSettings.subagent_error_penalty;
         const reason = `Subagent session ${targetSessionKey} ended with error`;
 
-        writePainFlag(workspaceDir, {
-            source: `subagent_error`,
+        writePainFlag(workspaceDir, buildPainFlag({
+            source: 'subagent_error',
             score: String(score),
-            time: new Date().toISOString(),
             reason,
-            is_risky: 'true',
+            is_risky: true,
             session_id: ctx.sessionId || '',
             agent_id: ctx.agentId || extractAgentIdFromSessionKey(targetSessionKey) || '',
-        });
+        }));
 
         emitSubagentPainEvent(wctx, {
             source: `subagent_error`,

package/src/service/evolution-worker.ts

@@ -586,7 +586,9 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
 
                 return doEnqueuePainTask(wctx, logger, painFlagPath, result, {
                     score: jsonScore, source: jsonSource, reason: jsonReason,
-                    preview: jsonPreview, traceId: '', sessionId: '', agentId: '',
+                    preview: jsonPreview, traceId: '',
+                    sessionId: jsonPain.session_id || '',
+                    agentId: jsonPain.agent_id || '',
                 });
             }
         } catch { /* Not JSON — fall through to KV/Markdown parsing */ }
@@ -935,6 +937,48 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                 }
             } catch {}
 
+            // ── Context Enrichment (CTX-01): Dual-path strategy ──
+            // P1: OpenClaw built-in tools (sessions_history) - safe, visibility-limited
+            // P2: JSONL direct read - fallback when tools fail or session not visible
+            // The diagnostician skill implements both paths (Phase 0 protocol).
+            //
+            // Here we pre-extract JSONL context as backup and inject tool instructions.
+
+            let contextSection = '';
+            if (highestScoreTask.session_id && highestScoreTask.agent_id) {
+                try {
+                    const { extractRecentConversation, extractFailedToolContext } = await import('../core/pain-context-extractor.js');
+                    const conversation = await extractRecentConversation(highestScoreTask.session_id, highestScoreTask.agent_id, 5);
+                    
+                    if (conversation) {
+                        contextSection = `\n## Recent Conversation Context (pre-extracted JSONL fallback)\n\n${conversation}\n`;
+                        
+                        // Also try to extract failed tool context if this is a tool failure
+                        if (highestScoreTask.source === 'tool_failure') {
+                            const toolMatch = highestScoreTask.reason?.match(/Tool ([\w-]+) failed/);
+                            const fileMatch = highestScoreTask.reason?.match(/on (.+?)(?=\s*Error:|$)/i);
+                            if (toolMatch) {
+                                const toolContext = await extractFailedToolContext(
+                                    highestScoreTask.session_id,
+                                    highestScoreTask.agent_id,
+                                    toolMatch[1],
+                                    fileMatch?.[1]?.trim(),
+                                );
+                                if (toolContext) {
+                                    contextSection += `\n## Failed Tool Call Context\n\n${toolContext}\n`;
+                                }
+                            }
+                        }
+                    }
+                    if (logger) {
+                        const turns = contextSection ? contextSection.split('\n').filter(l => l.startsWith('[User]') || l.startsWith('[Assistant]')).length : 0;
+                        logger?.debug?.(`[PD:EvolutionWorker] Pre-extracted ${turns} conversation turns for task ${highestScoreTask.id}`);
+                    }
+                } catch (e) {
+                    if (logger) logger.warn(`[PD:EvolutionWorker] Failed to extract conversation context for task ${highestScoreTask.id}: ${String(e)}. Diagnostician will use P1 tools or fallback.`);
+                }
+            }
+
             const heartbeatContent = [
                 `## Evolution Task [ID: ${highestScoreTask.id}]`,
                 ``,
@@ -946,12 +990,25 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                 `**Session ID**: ${highestScoreTask.session_id || 'N/A'}`,
                 `**Agent ID**: ${highestScoreTask.agent_id || 'main'}`,
                 ``,
+                `## Available Tools for Context Search (P1 - Preferred)`,
+                ``,
+                `1. **sessions_history** — Get full message history (requires sessionKey)`,
+                `2. **sessions_list** — List sessions (searches metadata only, NOT message content)`,
+                `3. **read_file / search_file_content** — Search codebase`,
+                ``,
+                `**P1 SOP**: sessions_history(sessionKey="agent:${highestScoreTask.agent_id || 'main'}:run:${highestScoreTask.session_id || 'N/A'}", limit=30)`,
+                ``,
+                `## Pre-extracted Context (P2 - JSONL Fallback)`,
+                `If OpenClaw tools cannot access the session (visibility limits),`,
+                `use this pre-extracted context below:`,
+                contextSection || `*(No JSONL context available — use P1 tools first)*`,
+                ``,
                 `---`,
                 ``,
                 `## Diagnostician Protocol`,
                 ``,
                 `You MUST use the **pd-diagnostician** skill for this task.`,
-                `Read the full skill definition and follow the 4-phase protocol (Evidence → Causal Chain → Classification → Principle Extraction) EXACTLY as specified.`,
+                `Read the full skill definition and follow the protocol EXACTLY as specified: Phase 0 (context extraction, optional) → Phase 1 (Evidence) → Phase 2 (Causal Chain) → Phase 3 (Classification) → Phase 4 (Principle Extraction).`,
                 `The skill defines the complete output contract — your JSON report MUST match the format specified in the skill.`,
                 ``,
                 `---`,

package/templates/langs/en/skills/pd-auditor/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: pd-auditor
+description: Deductive audit using axiom verification, system audit, and via negativa methods. TRIGGER CONDITIONS: (1) Need to audit system or process consistency (2) Verify core assumptions are self-consistent (3) Check component interactions are correct (4) Need to identify design flaws or logical contradictions.
+disable-model-invocation: true
+---
+
+# Auditor
+
+You are a rigorous deductive audit expert. Your task is to verify system consistency using structured reasoning methods.
+
+## Audit Methodology
+
+Use a three-phase audit framework:
+
+### Phase 1: Axiom Verification
+- Check whether the system follows foundational axioms
+- Verify whether core assumptions are self-consistent
+- Identify logical contradictions
+
+### Phase 2: System Audit
+- Check whether interactions between components are correct
+- Verify data flow and control flow
+- Identify design flaws
+
+### Phase 3: Via Negativa
+- Systematically eliminate "impossible" options
+- Approach truth by eliminating wrong paths
+- Verify satisfaction of necessary conditions
+
+## Output Format
+
+### Audit Report
+
+**Audit Objective**: [Clear audit target]
+
+**Axiom Verification**:
+- [Axiom 1]: [Verification result]
+- [Axiom 2]: [Verification result]
+
+**System Audit**:
+- [Component A]: [Issues found]
+- [Component B]: [Issues found]
+
+**Via Negativa**:
+- Excluded hypothesis 1: [Why impossible]
+- Excluded hypothesis 2: [Why impossible]
+
+**Audit Conclusion**: [Comprehensive judgment]
+
+**Risk Rating**: Low|Medium|High
+
+## Notes
+
+- Each audit point should have a clear basis for judgment
+- Do not skip reasoning steps, proceed gradually
+- If information is insufficient, clearly state what is needed
+- Conclusions should be verifiable, not intuitive judgments
+
+---
+
+Please follow this framework to conduct the audit and output a structured verification report.