principles-disciple 1.26.0 → 1.28.0

package/src/core/trajectory.ts

@@ -961,6 +961,17 @@ export class TrajectoryDatabase {
       throw new SampleNotFoundError(`${sampleId} (after update)`);
     }
 
+    // #Phase2b: Emit pain event for rejected corrections
+    if (status === 'rejected') {
+      this.recordCorrectionRejectedPain({
+        session_id: record.session_id,
+        quality_score: record.quality_score,
+        diff_excerpt: record.diff_excerpt,
+        principle_ids_json: record.principle_ids_json,
+        created_at: record.created_at,
+      });
+    }
+
     return {
       sampleId: String(record.sample_id),
       sessionId: String(record.session_id),
@@ -977,6 +988,43 @@ export class TrajectoryDatabase {
     };
   }
 
+  /**
+   * When a correction sample is rejected, emit a pain event to the trajectory.
+   * This feeds rejected corrections into the nocturnal pipeline as a high-fidelity
+   * violation signal (human-verified, unlike heuristic pain detection).
+   */
+  private recordCorrectionRejectedPain(record: {
+    session_id: unknown;
+    quality_score: unknown;
+    diff_excerpt: unknown;
+    principle_ids_json: unknown;
+    created_at: unknown;
+  }): void {
+    const sessionId = String(record.session_id);
+    const qualityScore = Number(record.quality_score);
+    const diffExcerpt = String(record.diff_excerpt ?? '');
+    const principleIds = String(record.principle_ids_json ?? '[]');
+    // quality_score (0-100) from correction sample → pain score (0-100), clamped
+    const painScore = Math.max(0, Math.min(100, Math.round(Number(qualityScore) || 0)));
+    const reason = `Correction rejected (quality ${qualityScore.toFixed(2)}). Principles: ${principleIds}${diffExcerpt ? ` — ${diffExcerpt.slice(0, 120)}` : ''}`;
+
+    try {
+      this.recordPainEvent({
+        sessionId,
+        source: 'correction_rejected',
+        score: painScore,
+        reason,
+        severity: painScore >= 70 ? 'severe' : painScore >= 40 ? 'moderate' : 'mild',
+        origin: 'system_infer',
+        text: diffExcerpt || undefined,
+        createdAt: String(record.created_at),
+      });
+    } catch (err) {
+      // Non-fatal: pain event recording should not break the review flow
+      console.warn(`[Trajectory] Failed to record correction_rejected pain event: ${String(err)}`);
+    }
+  }
+
   /**
    * Export correction samples to JSONL file.
    *
@@ -1496,6 +1544,11 @@ export class TrajectoryDatabase {
     `).get(sessionId) as Record<string, unknown> | undefined;
     if (!correctionTurn || !correctionTurn.references_assistant_turn_id) return;
 
+    // #Phase2b-fix: Tool failure is NOT required for correction samples.
+    // User corrections are the highest-fidelity signal — they indicate the agent
+    // said or did something wrong, regardless of whether tool calls succeeded.
+    // Requiring tool failure excluded the most valuable cases: "agent did something
+    // that technically worked but violated a principle or was logically wrong."
     const failedCall = this.db.prepare(`
       SELECT id, tool_name, error_type, error_message
       FROM tool_calls
@@ -1503,26 +1556,37 @@ export class TrajectoryDatabase {
       ORDER BY id DESC
       LIMIT 1
     `).get(sessionId) as Record<string, unknown> | undefined;
-    if (!failedCall) return;
 
-    const successfulCalls = this.db.prepare(`
-      SELECT id, tool_name
+    const recentCalls = this.db.prepare(`
+      SELECT id, tool_name, outcome
       FROM tool_calls
-      WHERE session_id = ? AND outcome = 'success'
+      WHERE session_id = ?
       ORDER BY id DESC
-      LIMIT 3
+      LIMIT 5
     `).all(sessionId) as Record<string, unknown>[];
-    if (successfulCalls.length === 0) return;
 
-    const sampleId = `sample_${crypto.createHash('md5').update(`${sessionId}:${correctionTurn.id}:${successfulCalls[0].id}`).digest('hex').slice(0, 12)}`;
+    const successfulCalls = recentCalls.filter(c => c.outcome === 'success');
+
+    // Generate sample ID from correction turn + first recent call (or correction id if no calls)
+    const refForHash = successfulCalls[0]?.id ?? correctionTurn.id;
+    const sampleId = `sample_${crypto.createHash('md5').update(`${sessionId}:${correctionTurn.id}:${refForHash}`).digest('hex').slice(0, 12)}`;
     const userRawText = this.restoreRawText(correctionTurn.raw_text as string | null, correctionTurn.blob_ref as string | null);
+
+    // Quality scoring: correction cue is always valuable
+    // Tool failure adds context (20pts), successful calls add context (up to 15pts)
+    // Pure conversation corrections still score 55-75 (high enough to review)
     const qualityScore = [
       correctionTurn.references_assistant_turn_id ? 35 : 0,
       correctionTurn.correction_cue ? 20 : 0,
       failedCall ? 20 : 0,
-      successfulCalls.length > 0 ? 25 : 0,
+      Math.min(successfulCalls.length, 3) * 5,
     ].reduce((sum, value) => sum + value, 0);
 
+    // Diff excerpt: prefer user correction text, fallback to error info, fallback to cue
+    const diffText = userRawText
+      || (failedCall ? String(failedCall.error_message ?? failedCall.error_type ?? failedCall.tool_name) : '')
+      || String(correctionTurn.correction_cue ?? 'user correction');
+
     this.withWrite(() => {
       this.db.prepare(`
         INSERT OR IGNORE INTO correction_samples (
@@ -1535,8 +1599,8 @@ export class TrajectoryDatabase {
         sessionId,
         Number(correctionTurn.references_assistant_turn_id),
         Number(correctionTurn.id),
-        safeJson(successfulCalls.map((call) => ({ id: call.id, toolName: call.tool_name }))),
-        summarizeForDiff(userRawText || String(failedCall.error_message ?? failedCall.error_type ?? failedCall.tool_name)),
+        safeJson(successfulCalls.map((call) => ({ id: call.id, toolName: call.tool_name, outcome: call.outcome }))),
+        summarizeForDiff(diffText),
         '[]',
         qualityScore,
         nowIso(),

package/src/index.ts

@@ -57,6 +57,7 @@ import { ensureWorkspaceTemplates } from './core/init.js';
 import { migrateDirectoryStructure } from './core/migration.js';
 import { SystemLogger } from './core/system-logger.js';
 import { createDeepReflectTool } from './tools/deep-reflect.js';
+import { createWritePainFlagTool } from './tools/write-pain-flag.js';
 import { PathResolver, resolveWorkspaceDirFromApi } from './core/path-resolver.js';
 import { validateWorkspaceDir } from './core/workspace-dir-validation.js';
 import { resolveRequiredWorkspaceDir, resolveWorkspaceDir, type WorkspaceResolutionContext } from './core/workspace-dir-service.js';
@@ -773,6 +774,7 @@ const plugin = {
     });
 
     api.registerTool(createDeepReflectTool(api));
+    api.registerTool(createWritePainFlagTool(api));
   }
 };
 

package/src/service/evolution-worker.ts

@@ -356,7 +356,8 @@ function isSessionAtOrBeforeTriggerTime(
 
 function buildFallbackNocturnalSnapshot(
     sleepTask: EvolutionQueueItem,
-    extractor?: ReturnType<typeof createNocturnalTrajectoryExtractor> | null
+    extractor?: ReturnType<typeof createNocturnalTrajectoryExtractor> | null,
+    logger?: { warn?: (message: string) => void }
 ): NocturnalSessionSnapshot | null {
     const painContext = sleepTask.recentPainContext;
     if (!painContext) {
@@ -390,8 +391,10 @@ function buildFallbackNocturnalSnapshot(
                     totalGateBlocks: match.gateBlockCount,
                 };
             }
-        } catch {
-            // Best effort — non-fatal
+        } catch (err) {
+            // #260: Log extraction failures — silent swallowing makes debugging impossible
+            // and can mask systemic trajectory DB issues.
+            logger?.warn?.(`[PD:EvolutionWorker] Failed to extract real stats for session ${painContext.mostRecent?.sessionId} (falling back to zeros): ${String(err)}`);
         }
     }
 
@@ -590,63 +593,154 @@ export function readRecentPainContext(wctx: WorkspaceContext): RecentPainContext
     return { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 };
 }
 
+/**
+ * Build a dedup key from pain context.
+ * Returns null when no pain context is available (bypasses dedup).
+ */
+function buildPainSourceKey(
+    painCtx: ReturnType<typeof readRecentPainContext>,
+): string | null {
+    if (!painCtx.mostRecent) return null;
+    return `${painCtx.mostRecent.source}::${painCtx.mostRecent.reason?.slice(0, 50) ?? ''}`;
+}
+
+/**
+ * Check whether a similar sleep_reflection task completed recently.
+ * Phase 3c: Prevents redundant reflections of the same underlying issue.
+ */
+function hasRecentSimilarReflection(
+    queue: EvolutionQueueItem[],
+    painSourceKey: string,
+    now: number,
+): EvolutionQueueItem | null {
+    const DEDUP_WINDOW_MS = 4 * 60 * 60 * 1000; // 4 hours
+    return queue.find((t) => {
+        if (t.taskKind !== 'sleep_reflection') return false;
+        // Only match completed tasks (exclude failed to allow retries)
+        if (t.status !== 'completed') return false;
+        if (!t.completed_at) return false;
+        const age = now - new Date(t.completed_at).getTime();
+        if (age > DEDUP_WINDOW_MS) return false;
+        const taskPainKey = buildPainSourceKey(t.recentPainContext ?? { mostRecent: null, recentPainCount: 0, recentMaxPainScore: 0 });
+        // If either side has no pain context, they don't match
+        if (!taskPainKey) return false;
+        return taskPainKey === painSourceKey;
+    }) ?? null;
+}
+
+/**
+ * Check whether a specific task kind has a pending or in-progress entry.
+ */
+function hasPendingTask(queue: EvolutionQueueItem[], taskKind: string): boolean {
+    return queue.some(
+        (t) => t.taskKind === taskKind && (t.status === 'pending' || t.status === 'in_progress'),
+    );
+}
+
+/**
+ * Decide whether to skip enqueuing due to a recent similar reflection.
+ * Returns true if skipped (with log), false if should proceed.
+ */
+function shouldSkipForDedup(
+    queue: EvolutionQueueItem[],
+    wctx: WorkspaceContext,
+    logger: PluginLogger,
+): boolean {
+    const recentPainContext = readRecentPainContext(wctx);
+    const painSourceKey = buildPainSourceKey(recentPainContext);
+
+    // Bypass dedup when there is no pain context — general idle reflections
+    // should not be throttled by the 'no_pain_context' sentinel.
+    if (!painSourceKey) return false;
+
+    const now = Date.now();
+    const recentSimilarReflection = hasRecentSimilarReflection(queue, painSourceKey, now);
+
+    if (recentSimilarReflection) {
+        const completedTime = new Date(recentSimilarReflection.completed_at!).getTime();
+        logger?.debug?.(`[PD:EvolutionWorker] Skipping sleep_reflection — similar reflection completed ${Math.round((now - completedTime) / 60000)}min ago (same pain pattern: ${painSourceKey})`);
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Load and migrate the evolution queue. Returns empty array if file doesn't exist.
+ */
+function loadEvolutionQueue(queuePath: string): EvolutionQueueItem[] {
+    let rawQueue: RawQueueItem[] = [];
+    try {
+        rawQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+    } catch {
+        // Queue doesn't exist yet - create empty array
+        rawQueue = [];
+    }
+    return migrateQueueToV2(rawQueue);
+}
+
+/**
+ * Build and persist a new sleep_reflection task.
+ */
+function enqueueNewSleepReflectionTask(
+    queue: EvolutionQueueItem[],
+    recentPainContext: ReturnType<typeof readRecentPainContext>,
+    queuePath: string,
+    logger: PluginLogger,
+): void {
+    const taskId = createEvolutionTaskId('nocturnal', 50, 'idle workspace', 'Sleep-mode reflection', Date.now());
+    const nowIso = new Date().toISOString();
+
+    queue.push({
+        id: taskId,
+        taskKind: 'sleep_reflection',
+        priority: 'medium',
+        score: 50,
+        source: 'nocturnal',
+        reason: 'Sleep-mode reflection triggered by idle workspace',
+        trigger_text_preview: 'Idle workspace detected',
+        timestamp: nowIso,
+        enqueued_at: nowIso,
+        status: 'pending',
+        traceId: taskId,
+        retryCount: 0,
+        maxRetries: 1, // sleep_reflection doesn't retry
+        recentPainContext,
+    });
+
+    fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
+    logger?.info?.(`[PD:EvolutionWorker] Enqueued sleep_reflection task ${taskId}`);
+}
+
 /**
  * Enqueue a sleep_reflection task if one is not already pending.
  * Phase 2.4: Called when workspace is idle to trigger nocturnal reflection.
+ * Phase 3c: Dedup checks recent sleep_reflection tasks by pain source pattern
+ * to prevent redundant reflections of the same underlying issue.
  */
 async function enqueueSleepReflectionTask(
     wctx: WorkspaceContext,
-    logger: PluginLogger
+    logger: PluginLogger,
 ): Promise<void> {
     const queuePath = wctx.resolve('EVOLUTION_QUEUE');
     const releaseLock = await requireQueueLock(queuePath, logger, 'enqueueSleepReflection', EVOLUTION_QUEUE_LOCK_SUFFIX);
 
     try {
-        let rawQueue: RawQueueItem[] = [];
-        try {
-            rawQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
-        } catch {
-            // Queue doesn't exist yet - create empty array
-            rawQueue = [];
-        }
-
-        const queue: EvolutionQueueItem[] = migrateQueueToV2(rawQueue);
+        const queue = loadEvolutionQueue(queuePath);
 
-        // Check if a sleep_reflection task is already pending
-        const hasPendingSleepReflection = queue.some(
-            t => t.taskKind === 'sleep_reflection' && (t.status === 'pending' || t.status === 'in_progress')
-        );
-        if (hasPendingSleepReflection) {
+        // Guard 1: Skip if a sleep_reflection task is already pending/in-progress
+        if (hasPendingTask(queue, 'sleep_reflection')) {
             logger?.debug?.('[PD:EvolutionWorker] sleep_reflection task already pending/in-progress, skipping');
             return;
         }
 
-        const now = Date.now();
-        const taskId = createEvolutionTaskId('nocturnal', 50, 'idle workspace', 'Sleep-mode reflection', now);
-        const nowIso = new Date(now).toISOString();
+        // Guard 2: Dedup — skip if similar reflection completed recently
+        if (shouldSkipForDedup(queue, wctx, logger)) {
+            return;
+        }
 
-        // Attach recent pain context if available
+        // Enqueue the new task
         const recentPainContext = readRecentPainContext(wctx);
-
-        queue.push({
-            id: taskId,
-            taskKind: 'sleep_reflection',
-            priority: 'medium',
-            score: 50,
-            source: 'nocturnal',
-            reason: 'Sleep-mode reflection triggered by idle workspace',
-            trigger_text_preview: 'Idle workspace detected',
-            timestamp: nowIso,
-            enqueued_at: nowIso,
-            status: 'pending',
-            traceId: taskId,
-            retryCount: 0,
-            maxRetries: 1, // sleep_reflection doesn't retry
-            recentPainContext,
-        });
-
-        fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2), 'utf8');
-        logger?.info?.(`[PD:EvolutionWorker] Enqueued sleep_reflection task ${taskId}`);
+        enqueueNewSleepReflectionTask(queue, recentPainContext, queuePath, logger);
     } finally {
         releaseLock();
     }
@@ -1565,7 +1659,7 @@ 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 snapshot unavailable, will try session summary from extractor`);
-                            snapshotData = buildFallbackNocturnalSnapshot(sleepTask, extractor) ?? undefined;
+                            snapshotData = buildFallbackNocturnalSnapshot(sleepTask, extractor, logger) ?? undefined;
                         }
 
                         const snapshotValidation = validateNocturnalSnapshotIngress(snapshotData);

package/src/tools/write-pain-flag.ts

@@ -0,0 +1,191 @@
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+import { Type } from '@sinclair/typebox';
+import { buildPainFlag, writePainFlag } from '../core/pain.js';
+import { resolveWorkspaceDirFromApi } from '../core/path-resolver.js';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Pain flag contract required fields
+const PAIN_FLAG_REQUIRED_FIELDS = ['source', 'score', 'time', 'reason'] as const;
+
+/**
+ * Atomic file write: write to temp file then rename.
+ * Prevents corruption if process crashes mid-write.
+ */
+function writePainFlagAtomic(filePath: string, content: string): void {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const tmpPath = `${filePath}.tmp.${Date.now()}.${process.pid}`;
+    fs.writeFileSync(tmpPath, content, 'utf-8');
+    fs.renameSync(tmpPath, filePath);
+}
+
+/**
+ * Creates the `write_pain_flag` tool.
+ *
+ * This tool allows the agent to record a pain signal when it recognizes
+ * that it made a mistake, violated a principle, or needs to flag an issue
+ * for later reflection.
+ *
+ * The tool wraps `buildPainFlag` + atomic `writePainFlag` to ensure:
+ * - Correct KV format serialization (never [object Object] corruption)
+ * - Atomic writes (temp file + rename, crash-safe)
+ * - Full contract compliance (source, score, time, reason)
+ *
+ * The agent should NEVER write to .pain_flag directly.
+ */
+export function createWritePainFlagTool(api: OpenClawPluginApi) {
+    return {
+        name: 'write_pain_flag',
+        description:
+            'Record a pain signal to flag mistakes, principle violations, or issues for later reflection. ' +
+            'Use this tool INSTEAD of writing .pain_flag directly. ' +
+            'Pain signals are processed by the evolution system on the next heartbeat cycle.',
+        parameters: Type.Object({
+            reason: Type.String({
+                description:
+                    'Describe specifically what went wrong. ' +
+                    'Include the error, the violated principle, or the issue. ' +
+                    'Be concrete: "I edited config.ts without reading it first, breaking the export" ' +
+                    'is better than "I made a mistake".',
+            }),
+            score: Type.Optional(Type.Number({
+                description:
+                    'Pain severity score (0-100). Default: 80. ' +
+                    'Guidelines: 30-50 (minor issue), 50-70 (moderate error), ' +
+                    '70-100 (severe principle violation or data loss risk).',
+                minimum: 0,
+                maximum: 100,
+            })),
+            source: Type.Optional(Type.String({
+                description:
+                    'Source of the pain signal. ' +
+                    'Values: manual (user flagged), tool_failure (tool error), ' +
+                    'user_empathy (user frustration), principle_violation (principle broken), ' +
+                    'human_intervention (user manually intervened). ' +
+                    'Default: manual.',
+            })),
+            session_id: Type.Optional(Type.String({
+                description:
+                    'Session ID where the pain occurred. ' +
+                    'If not provided, the system will use the current session.',
+            })),
+            is_risky: Type.Optional(Type.Boolean({
+                description:
+                    'Whether this involves a high-risk operation (e.g., writing to sensitive files). ' +
+                    'Default: false.',
+            })),
+        }),
+
+        async execute(
+            _toolCallId: string,
+            rawParams: Record<string, unknown>
+        ): Promise<{ content: { type: string; text: string }[] }> {
+            const reason = typeof rawParams.reason === 'string' ? rawParams.reason.trim() : '';
+            const score = typeof rawParams.score === 'number' ? Math.max(0, Math.min(100, Math.round(rawParams.score))) : 80;
+            const source = typeof rawParams.source === 'string' && rawParams.source.trim() ? rawParams.source.trim() : 'manual';
+            const sessionId = typeof rawParams.session_id === 'string' ? rawParams.session_id.trim() : '';
+            const isRisky = rawParams.is_risky === true;
+
+            // ── Validate required fields ──
+            if (!reason) {
+                api.logger?.warn?.('[PD:write_pain_flag] Missing required field: reason');
+                return {
+                    content: [{
+                        type: 'text',
+                        text: '❌ Error: The `reason` parameter is required.\n' +
+                            'Describe specifically what went wrong. Example:\n' +
+                            '"I edited config.ts without reading it first, breaking the export"',
+                    }],
+                };
+            }
+
+            // ── Resolve workspace ──
+            const workspaceDir = resolveWorkspaceDirFromApi(api);
+            if (!workspaceDir) {
+                api.logger?.error?.('[PD:write_pain_flag] Cannot resolve workspace directory');
+                return {
+                    content: [{
+                        type: 'text',
+                        text: '❌ Error: Cannot determine the workspace directory. ' +
+                            'Please ensure you are in an active workspace.',
+                    }],
+                };
+            }
+
+            try {
+                // ── Build pain flag data (KV format) ──
+                const painData = buildPainFlag({
+                    source,
+                    score: String(score),
+                    reason,
+                    session_id: sessionId,
+                    is_risky: isRisky,
+                });
+
+                // ── Validate contract compliance ──
+                const missingFields: string[] = [];
+                for (const field of PAIN_FLAG_REQUIRED_FIELDS) {
+                    if (!painData[field] || painData[field].trim() === '') {
+                        missingFields.push(field);
+                    }
+                }
+                if (missingFields.length > 0) {
+                    api.logger?.error?.(`[PD:write_pain_flag] Pain flag missing required fields: ${missingFields.join(', ')}`);
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: `❌ Error: Pain flag is missing required fields: ${missingFields.join(', ')}. ` +
+                                'This is an internal error — please report it.',
+                        }],
+                    };
+                }
+
+                // ── Atomic write (temp file + rename) ──
+                const painFlagPath = path.join(workspaceDir, '.state', '.pain_flag');
+                const { serializeKvLines } = await import('../utils/io.js');
+                const content = serializeKvLines(painData);
+                writePainFlagAtomic(painFlagPath, content);
+
+                // ── Log success ──
+                api.logger?.info?.(
+                    `[PD:write_pain_flag] Pain signal recorded: source=${source}, score=${score}, ` +
+                    `reason="${reason.slice(0, 80)}"${reason.length > 80 ? '...' : ''}"`
+                );
+
+                // ── Agent feedback ──
+                return {
+                    content: [{
+                        type: 'text',
+                        text: `✅ Pain signal recorded successfully.\n\n` +
+                            `- **Reason**: ${reason}\n` +
+                            `- **Score**: ${score}/100\n` +
+                            `- **Source**: ${source}\n` +
+                            `- **Risk**: ${isRisky ? 'Yes' : 'No'}\n` +
+                            `- **Session**: ${sessionId || '(current)'}\n\n` +
+                            `The evolution system will process this signal on the next heartbeat cycle ` +
+                            `(typically within 60 seconds).`,
+                    }],
+                };
+            } catch (err) {
+                // ── Log failure with stack trace ──
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                const stack = err instanceof Error ? err.stack?.split('\n').slice(0, 3).join(' → ') : '';
+                api.logger?.error?.(
+                    `[PD:write_pain_flag] Failed to write pain flag: ${errorMsg}` +
+                    (stack ? `\n  Stack: ${stack}` : '')
+                );
+
+                return {
+                    content: [{
+                        type: 'text',
+                        text: `❌ Failed to record pain signal: ${errorMsg}\n\n` +
+                            'The error has been logged. Please try again or report this issue.',
+                    }],
+                };
+            }
+        },
+    };
+}

package/templates/langs/en/skills/pd-pain-signal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pd-pain-signal
-description: Manually inject a pain signal into the evolution system by writing to .state/.pain_flag. TRIGGER CONDITIONS: (1) User reports agent stuck/looping/unresponsive (2) User says "record this issue", "force reflection", "trigger pain" (3) Tool failure with no follow-up action (4) User provides human intervention feedback.
+description: Manually inject a pain signal into the evolution system. TRIGGER CONDITIONS: (1) User reports agent stuck/looping/unresponsive (2) User says "record this issue", "force reflection", "trigger pain" (3) Tool failure with no follow-up action (4) User provides human intervention feedback.
 disable-model-invocation: true
 ---
 
@@ -9,30 +9,44 @@ disable-model-invocation: true
 You are now the "Manual Intervention Pain" component.
 
 **Task**:
-1. Write the user's feedback `$ARGUMENTS` as a **high-priority** pain signal to `.state/.pain_flag`.
+1. Record the user's feedback `$ARGUMENTS` as a **high-priority** pain signal.
 2. Inform the user that the signal has been injected, and suggest waiting for the next Hook trigger (e.g., Stop or PreCompact) or manually running `/reflection-log`.
 
-**Write Format** (must use this KV format, fields sorted alphabetically):
+**⚠️ Write Rules (MUST follow)**
+
+**The ONLY correct way**: Use the `write_pain_flag` tool.
 
 ```
-agent_id: <current agent ID, e.g., main/builder/diagnostician>
-is_risky: false
-reason: <user's feedback verbatim>
-score: 80
-session_id: <current session ID>
-source: human_intervention
-time: <ISO 8601 timestamp>
+write_pain_flag({
+  reason: "User feedback or error description",
+  score: 80,
+  source: "human_intervention",
+  is_risky: false
+})
 ```
 
-**Required fields** (4):
-- `source`: Fixed as `human_intervention`
-- `score`: Default `80` for manual intervention (high priority)
-- `time`: ISO 8601 timestamp
-- `reason`: User's feedback verbatim
+**Absolutely forbidden**:
+- ❌ Writing to `.state/.pain_flag` directly (any method)
+- ❌ Using bash heredoc (`cat <<EOF > .pain_flag`)
+- ❌ Using `echo "..." > .pain_flag`
+- ❌ Using `node -e` to call `writePainFlag` or `buildPainFlag`
+- ❌ Any method that `toString()` a JavaScript object to the file
+
+**Why use the tool?**
+The `write_pain_flag` tool encapsulates correct KV-format serialization, ensuring `.pain_flag` is never corrupted. Historically, direct file writes caused `[object Object]` corruption multiple times.
 
-**Optional fields** (auto-filled by system, but must be provided for manual injection):
-- `agent_id`: Current agent ID (e.g., main/builder/diagnostician)
-- `session_id`: Current session ID (from context)
-- `is_risky`: Fixed as `false`
+**Parameters**:
+- `reason` (required): The reason for the pain signal — describe what went wrong
+- `score` (optional): Pain score 0-100, default 80 (manual intervention)
+- `source` (optional): Source, default `human_intervention`
+- `is_risky` (optional): Whether this is a high-risk action, default false
 
-**Note**: `trace_id` and `trigger_text_preview` are auto-generated by the system — do NOT include them when manually injecting pain signals.
+**Example**:
+```
+write_pain_flag({
+  reason: "Agent edited a file without reading it first, breaking existing logic",
+  score: 85,
+  source: "human_intervention",
+  is_risky: false
+})
+```