principles-disciple 1.53.0 → 1.55.0

package/.planning/phases/01-basic-visualization/01-GAP-CLOSURE-VERIFICATION.md

@@ -0,0 +1,113 @@
+---
+phase: "01-basic-visualization"
+plan: "01-GAP-CLOSURE"
+verified: 2026-04-17T15:30:00Z
+status: passed
+score: "4/4 must-haves verified"
+overrides_applied: 0
+re_verification: false
+gaps: []
+deferred: []
+human_verification: []
+requirement_mismatch:
+  note: "Requirement IDs provided (SDK-CORE-03, SDK-ADP-07, SDK-ADP-08, SDK-TEST-02, SDK-TEST-03, SDK-MGMT-01, SDK-MGMT-02) are SDK Core Implementation Phase 1 requirements per REQUIREMENTS.md. This phase (01-basic-visualization) addresses VIZ-04 (Empty state optimization) - a different domain. Requirement coverage cannot be established for IDs that do not belong to this phase."
+---
+
+# Phase 01-basic-visualization: GAP-CLOSURE Verification Report
+
+**Phase Goal:** Close verification gaps from Phase 01 by implementing missing i18n fixes for LineChart component and coverage trend empty state.
+**Verified:** 2026-04-17T15:30:00Z
+**Status:** passed
+**Re-verification:** No — initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| #   | Truth | Status | Evidence |
+| --- | ----- | ------ | -------- |
+| 1   | LineChart interface has emptyText prop for i18n | VERIFIED | `emptyText?: string;` at line 864 in charts.tsx |
+| 2   | LineChart renders emptyText prop instead of hardcoded '暂无数据' | VERIFIED | Conditional render at lines 878-885: `if (!emptyText) return null;` then `{emptyText}` |
+| 3   | Coverage trend section shows EmptyState when no data | VERIFIED | Ternary at line 259: `data.coverageTrend.length >= 1 ? (...) : (<EmptyState ...>)` |
+| 4   | All LineChart usages pass emptyText prop | VERIFIED | Lines 272, 454, 521 all have `emptyText={t('common.noData')}` |
+
+**Score:** 4/4 truths verified
+
+### Deferred Items
+
+None
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+| -------- | -------- | ------ | ------- |
+| `charts.tsx:864` | `emptyText?: string` in LineChartProps | VERIFIED | Prop exists at correct line |
+| `charts.tsx:876` | Default value `emptyText = ''` | VERIFIED | Default empty string assigned |
+| `charts.tsx:878-885` | Conditional render using emptyText | VERIFIED | Returns null if no emptyText, renders div with {emptyText} otherwise |
+| `ThinkingModelsPage.tsx:259` | Ternary operator for coverage trend | VERIFIED | `data.coverageTrend.length >= 1 ? (...) : (<EmptyState ...>)` |
+| `ThinkingModelsPage.tsx:272` | LineChart with emptyText prop | VERIFIED | `emptyText={t('common.noData')}` |
+| `ThinkingModelsPage.tsx:454` | LineChart with emptyText prop | VERIFIED | `emptyText={t('common.noData')}` |
+| `ThinkingModelsPage.tsx:521` | LineChart with emptyText prop | VERIFIED | `emptyText={t('common.noData')}` |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+| ---- | --- | --- | ------ | ------- |
+| LineChart | i18n system | emptyText prop | WIRED | emptyText prop accepts i18n string and renders it |
+| Coverage trend | EmptyState | ternary operator | WIRED | Ternary correctly switches between LineChart and EmptyState |
+| ThinkingModelsPage | common.noData | t() function | WIRED | All LineChart usages pass i18n key |
+| EmptyState | i18n keys | t() function | WIRED | `t('thinkingModels.emptyCoverageTrend')` and `t('thinkingModels.emptyCoverageTrendDesc')` used |
+
+### Data-Flow Trace (Level 4)
+
+| Artifact | Data Variable | Source | Produces Real Data | Status |
+| -------- | ------------- | ------ | ------------------ | ------ |
+| LineChart emptyText | emptyText prop | Parent component via t('common.noData') | N/A | STATIC — i18n key is static, not dynamic |
+
+### Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+| -------- | ------- | ------ | ------ |
+| emptyText in interface | `grep -n "emptyText?: string" charts.tsx` | `864:  emptyText?: string;` | PASS |
+| No hardcoded Chinese | `grep -n "暂无数据" charts.tsx` | No matches | PASS |
+| Ternary for coverage | `grep -n "coverageTrend.length.*?" ThinkingModelsPage.tsx` | `259: {data.coverageTrend.length >= 1 ?` | PASS |
+| EmptyState for coverage | `grep -n "EmptyState" ThinkingModelsPage.tsx \| head -3` | Lines 276-279 with i18n keys | PASS |
+| All LineChart have emptyText | `grep -B5 -A10 "<LineChart" ThinkingModelsPage.tsx \| grep -c "emptyText"` | 3 | PASS |
+
+### Requirements Coverage
+
+**IMPORTANT - Requirement Mismatch Found:**
+
+| Requirement | Source | Description | Status | Evidence |
+| ----------- | ------ | ----------- | ------ | -------- |
+| SDK-CORE-03 | User-provided | Implement universal PainSignal interface logic | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-ADP-07 | User-provided | Implement Coding domain adapter | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-ADP-08 | User-provided | Implement second domain adapter | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-TEST-02 | User-provided | Implement full Adapter conformance test suite | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-TEST-03 | User-provided | Execute and publish performance benchmarks | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-MGMT-01 | User-provided | Package SDK as @principles/core npm package | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-MGMT-02 | User-provided | Establish Semver versioning and migration guides | N/A | Does not belong to 01-basic-visualization phase |
+| VIZ-04 | GAP-CLOSURE-PLAN | Empty state optimization | VERIFIED | All 4 must_haves from GAP-CLOSURE-PLAN verified |
+
+**The 7 requirement IDs provided are SDK Core Implementation Phase 1 requirements per REQUIREMENTS.md. They do not map to the 01-basic-visualization phase. The phase's actual scope is VIZ-04 (Empty state optimization), which has been verified through must_haves.**
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+| ---- | ---- | ------- | -------- | ------ |
+| None | - | No anti-patterns detected | - | - |
+
+### Human Verification Required
+
+None required — all truths verifiable via static analysis.
+
+### Gaps Summary
+
+**None.** All 4 must_haves verified. Phase goal achieved.
+
+**Notable finding:** The requirement IDs provided by user (SDK-CORE-03, SDK-ADP-07, SDK-ADP-08, SDK-TEST-02, SDK-TEST-03, SDK-MGMT-01, SDK-MGMT-02) are SDK Core Implementation Phase 1 requirements per REQUIREMENTS.md. This phase (01-basic-visualization) addresses VIZ-04 (Empty state optimization for visualization) - a different scope. Requirement coverage cannot be established for IDs that do not belong to this phase.
+
+---
+
+_Verified: 2026-04-17T15:30:00Z_
+_Verifier: Claude (gsd-verifier)_

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.53.0",
+  "version": "1.55.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/src/core/bootstrap-rules.ts

@@ -82,7 +82,7 @@ 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);
+  let 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) {
@@ -115,6 +115,8 @@ export function bootstrapRules(stateDir: string, limit = 3): BootstrapResult[] {
       };
       addPrincipleToLedger(stateDir, lp);
     }
+    // Reload ledger after migration so subsequent reads see the new data.
+    ledger = loadLedger(stateDir);
   }
 
   // Select principles for bootstrap

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

@@ -15,7 +15,7 @@
  * SAFETY:
  * - Never load entire file (tail-only, max 512KB)
  * - Skip lines > 100KB (real files have 11MB single lines)
- * - Cap total output at 1500 chars
+ * - Cap total output at 2000 chars
  * - All errors caught silently — return empty string on failure
  */
 
@@ -35,9 +35,9 @@ 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;
+const MAX_TURN_CHARS = 400;
 /** Max total output */
-const MAX_OUTPUT_CHARS = 1500;
+const MAX_OUTPUT_CHARS = 2000;
 
 /** Valid characters for session IDs and agent IDs — prevents path traversal */
 const SAFE_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
@@ -155,19 +155,24 @@ function extractTurn(msg: ParsedMessage): string | null {
   }
 
   if (msg.role === 'assistant') {
-    // Priority 1: final text reply
+    const parts: string[] = [];
+    
+    // Priority 1: final text reply (if present)
     if (msg.textParts.length > 0) {
       const text = msg.textParts.join(' ').trim();
-      if (text) return `[Assistant]: ${text.substring(0, MAX_TURN_CHARS)}`;
+      if (text) parts.push(`[Assistant]: ${text.substring(0, MAX_TURN_CHARS)}`);
     }
-    // Priority 2: tool call summary (what operations were performed)
+    
+    // Priority 2: tool call summary (always include if present, for context)
     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(', ')}]`;
+        parts.push(`[Assistant → ${uniqueTools.join(', ')}]`);
       }
     }
+    
+    return parts.length > 0 ? parts.join(' ') : null;
   }
 
   if (msg.role === 'toolResult') {

package/src/core/pain-lifecycle.ts

@@ -0,0 +1,38 @@
+import * as fs from 'fs';
+import { resolvePdPath } from './paths.js';
+
+export const PAIN_FLAG_FILENAME = '.pain_flag';
+
+/**
+ * Removes the .pain_flag file from the workspace's .state directory.
+ * Called when a pain signal task completes (success, timeout, duplicate, or invalid)
+ * to prevent stale flags from triggering repeated processing.
+ *
+ * Optionally verifies the file content before deleting to prevent accidentally removing
+ * a concurrent new signal that was written between checkPainFlag reading the file and
+ * this deletion call (TOCTOU race).
+ *
+ * @param workspaceDir - Workspace directory
+ * @param expectedPainEventId - If provided, only deletes the file if its pain_event_id matches.
+ *                              This prevents deleting a newly written signal during a race window.
+ */
+export function clearPainFlag(workspaceDir: string, expectedPainEventId?: number | string): void {
+    const painFlagPath = resolvePdPath(workspaceDir, 'PAIN_FLAG');
+    try {
+        // Guard against TOCTOU race: if expectedPainEventId is provided,
+        // re-read the file and verify the pain_event_id matches before deleting.
+        // This prevents accidentally removing a new signal written between
+        // checkPainFlag reading the flag and this deletion.
+        if (expectedPainEventId !== undefined) {
+            const content = fs.readFileSync(painFlagPath, 'utf8');
+            const idMatch = content.includes(`pain_event_id: ${expectedPainEventId}`);
+            if (!idMatch) {
+                // File was rewritten with a different signal — do not delete.
+                return;
+            }
+        }
+        fs.unlinkSync(painFlagPath);
+    } catch {
+        // Best-effort cleanup — ENOENT means already gone, other errors are ignored.
+    }
+}

package/src/core/pain-signal.ts

@@ -48,11 +48,11 @@ export const PainSignalSchema = Type.Object({
   /** Human-readable reason / error description */
   reason: Type.String({ minLength: 1 }),
   /** Session ID — identifies which conversation this happened in */
-  sessionId: Type.String({ minLength: 1 }),
+  sessionId: Type.Optional(Type.String()),
   /** Agent ID — identifies which agent (main, builder, diagnostician, etc.) */
-  agentId: Type.String({ minLength: 1 }),
+  agentId: Type.Optional(Type.String()),
   /** Correlation trace ID for linking events across the pipeline */
-  traceId: Type.String({ minLength: 1 }),
+  traceId: Type.Optional(Type.String()),
   /** Preview of the text that triggered this pain */
   triggerTextPreview: Type.String(),
   /** Domain context (e.g., 'coding', 'writing', 'analysis') */
@@ -111,6 +111,9 @@ export function validatePainSignal(input: unknown): PainSignalValidationResult {
   const hydrated = {
     ...raw,
     domain: raw.domain ?? 'coding',
+    sessionId: raw.sessionId ?? undefined,
+    agentId: raw.agentId ?? undefined,
+    traceId: raw.traceId ?? undefined,
     severity: raw.severity ?? deriveSeverity(
       typeof raw.score === 'number' ? raw.score : 0,
     ),

package/src/service/event-log-auditor.ts

@@ -179,8 +179,16 @@ export async function auditEventLogs(
         recentEntries: recent,
       });
 
-      // Determine primary path (workspace-main or most recent)
-      if (filePath.includes('workspace-main') || filePath.includes('workspace-main')) {
+      // Determine primary path - prefer configured workspace over workspace-main
+      // The configured workspace path is {openclawDir}/workspace (without -main suffix)
+      const workspaceDir = path.join(openclawDir, 'workspace') + path.sep;
+      const workspaceMainDir = path.join(openclawDir, 'workspace-main') + path.sep;
+      
+      if (filePath.startsWith(workspaceDir)) {
+        // Configured workspace (e.g., ~/.openclaw/workspace/) takes priority
+        primaryPath = filePath;
+      } else if (!primaryPath && filePath.startsWith(workspaceMainDir)) {
+        // Fallback to workspace-main only if no configured workspace found yet
         primaryPath = filePath;
       }
     } catch {

package/src/service/evolution-worker.ts

@@ -52,6 +52,7 @@ import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
 import { classifyFailure, type ClassifiableTaskKind } from './failure-classifier.js';
 import { recordPersistentFailure, resetFailureState, isTaskKindInCooldown } from './cooldown-strategy.js';
 import { reconcileStartup } from './startup-reconciler.js';
+import { clearPainFlag } from '../core/pain-lifecycle.js';
 import { WORKFLOW_TTL_MS } from '../config/defaults/runtime.js';
 import { OpenClawTrinityRuntimeAdapter } from '../core/nocturnal-trinity.js';
 
@@ -338,9 +339,9 @@ async function doEnqueuePainTask(
         score: v.score,
         timestamp: new Date().toISOString(),
         reason: v.reason,
-        sessionId: v.sessionId || '',
-        agentId: v.agentId || '',
-        traceId: v.traceId || '',
+        sessionId: v.sessionId ?? undefined,
+        agentId: v.agentId ?? undefined,
+        traceId: v.traceId ?? undefined,
         triggerTextPreview: v.preview,
     };
     const validation: PainSignalValidationResult = validatePainSignal(signalInput);
@@ -348,6 +349,7 @@ async function doEnqueuePainTask(
         result.skipped_reason = `invalid_pain_signal (${validation.errors.join('; ')})`;
         if (logger) logger.warn(`[PD:EvolutionWorker] Pain signal validation failed, skipping enqueue: ${validation.errors.join('; ')}`);
         SystemLogger.log(wctx.workspaceDir, 'PAIN_SIGNAL_INVALID', `Validation errors: ${validation.errors.join('; ')} | source=${v.source} score=${v.score}`);
+        clearPainFlag(wctx.workspaceDir);
         return result;
     }
 
@@ -365,6 +367,7 @@ async function doEnqueuePainTask(
             result.enqueued = true;
             result.skipped_reason = 'duplicate';
             if (logger) logger.info(`[PD:EvolutionWorker] Duplicate pain task skipped for source=${v.source} preview=${v.preview || 'N/A'}`);
+            clearPainFlag(wctx.workspaceDir);
             return result;
         }
 
@@ -408,6 +411,7 @@ async function doEnqueuePainTask(
             enqueuedAt: nowIso,
         });
     } finally { releaseLock(); }
+    clearPainFlag(wctx.workspaceDir);
     return result;
 }
 
@@ -440,6 +444,7 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
             if (isQueued) {
                 result.skipped_reason = 'already_queued';
                 if (logger) logger.info(`[PD:EvolutionWorker] Pain flag already queued (score=${score}, source=${source})`);
+                clearPainFlag(wctx.workspaceDir, painEventId);
                 return result;
             }
 
@@ -453,6 +458,7 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
             result.exists = true;
             result.skipped_reason = `invalid_pain_flag (${contract.missingFields.join(', ') || contract.format})`;
             if (logger) logger.warn(`[PD:EvolutionWorker] Invalid pain flag skipped: ${result.skipped_reason}`);
+            clearPainFlag(wctx.workspaceDir);
             return result;
         }
 
@@ -493,6 +499,7 @@ async function checkPainFlag(wctx: WorkspaceContext, logger: PluginLogger): Prom
                     result.enqueued = true;
                     result.skipped_reason = 'already_queued';
                     if (logger) logger.info(`[PD:EvolutionWorker] Pain flag already queued (score=${jsonScore}, source=${jsonSource})`);
+                    clearPainFlag(wctx.workspaceDir, jsonPain.pain_event_id ? parseInt(jsonPain.pain_event_id, 10) : undefined);
                     return result;
                 }
 

package/tests/core/pain-lifecycle.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import { clearPainFlag, PAIN_FLAG_FILENAME } from '../../src/core/pain-lifecycle.js';
+import { resolvePdPath } from '../../src/core/paths.js';
+
+describe('PainLifecycle', () => {
+    const workspaceDir = fs.mkdtempSync(path.join(fs.realpathSync('/tmp'), 'pain-lifecycle-test-'));
+    const painFlagPath = resolvePdPath(workspaceDir, 'PAIN_FLAG');
+
+    beforeEach(() => {
+        const stateDir = path.dirname(painFlagPath);
+        if (!fs.existsSync(stateDir)) {
+            fs.mkdirSync(stateDir, { recursive: true });
+        }
+    });
+
+    afterEach(() => {
+        if (fs.existsSync(painFlagPath)) fs.unlinkSync(painFlagPath);
+    });
+
+    it('should delete .pain_flag file when it exists', () => {
+        fs.writeFileSync(painFlagPath, 'source: test\nscore: 80\nreason: test\ntime: 2026-01-01\n', 'utf8');
+        expect(fs.existsSync(painFlagPath)).toBe(true);
+        clearPainFlag(workspaceDir);
+        expect(fs.existsSync(painFlagPath)).toBe(false);
+    });
+
+    it('should not throw when .pain_flag does not exist', () => {
+        expect(fs.existsSync(painFlagPath)).toBe(false);
+        expect(() => clearPainFlag(workspaceDir)).not.toThrow();
+    });
+
+    it('should export correct filename constant', () => {
+        expect(PAIN_FLAG_FILENAME).toBe('.pain_flag');
+    });
+});

package/tests/core/pain-signal.test.ts

@@ -66,14 +66,14 @@ describe('PainSignalSchema', () => {
     expect(Value.Check(PainSignalSchema, signal)).toBe(false);
   });
 
-  it('rejects empty optional fields (sessionId, agentId, traceId, triggerTextPreview)', () => {
+  it('accepts empty optional fields (sessionId, agentId, etc.)', () => {
     const signal = validSignal({
       sessionId: '',
       agentId: '',
       traceId: '',
       triggerTextPreview: '',
     });
-    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+    expect(Value.Check(PainSignalSchema, signal)).toBe(true);
   });
 
   it('accepts any string for domain', () => {

package/tests/integration/pain-lifecycle-e2e.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import { clearPainFlag } from '../../src/core/pain-lifecycle.js';
+import { resolvePdPath } from '../../src/core/paths.js';
+
+describe('Pain Lifecycle E2E', () => {
+    const workspaceDir = fs.mkdtempSync(path.join(fs.realpathSync('/tmp'), 'pain-lifecycle-e2e-'));
+    const painFlagPath = resolvePdPath(workspaceDir, 'PAIN_FLAG');
+    const stateDir = path.dirname(painFlagPath);
+
+    beforeEach(() => {
+        if (!fs.existsSync(stateDir)) fs.mkdirSync(stateDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        if (fs.existsSync(painFlagPath)) fs.unlinkSync(painFlagPath);
+        if (fs.existsSync(stateDir)) {
+            try { fs.rmSync(stateDir, { recursive: true }); } catch { /* ignore */ }
+        }
+    });
+
+    it('should clear pain_flag after writing a valid flag', () => {
+        // Simulate write_pain_flag tool writing a flag
+        const kvContent = [
+            'source: tool_failure',
+            'score: 85',
+            'reason: Test pain signal',
+            'time: 2026-04-17T00:00:00.000Z',
+        ].join('\n') + '\n';
+        fs.writeFileSync(painFlagPath, kvContent, 'utf8');
+        expect(fs.existsSync(painFlagPath)).toBe(true);
+
+        // Simulate task enqueue → clear on exit path
+        clearPainFlag(workspaceDir);
+        expect(fs.existsSync(painFlagPath)).toBe(false);
+    });
+
+    it('should be idempotent — clearing twice should not throw', () => {
+        fs.writeFileSync(painFlagPath, 'source: test\nscore: 50\nreason: idem\ntime: 2026-01-01\n', 'utf8');
+        expect(() => clearPainFlag(workspaceDir)).not.toThrow();
+        expect(() => clearPainFlag(workspaceDir)).not.toThrow();
+    });
+
+    it('should not throw when .state directory does not exist', () => {
+        fs.rmSync(stateDir, { recursive: true, force: true });
+        expect(() => clearPainFlag(workspaceDir)).not.toThrow();
+    });
+
+    it('should NOT delete file when expectedPainEventId does not match (concurrent rewrite guard)', () => {
+        // Write a flag with pain_event_id: 5
+        fs.writeFileSync(painFlagPath, 'source: test\nscore: 80\nreason: old\ntime: 2026-01-01\npain_event_id: 5\n', 'utf8');
+        expect(fs.existsSync(painFlagPath)).toBe(true);
+
+        // Simulate: another write_pain_flag runs and writes a NEW signal (pain_event_id: 7)
+        // before our clearPainFlag with expected id=5 runs
+        fs.writeFileSync(painFlagPath, 'source: test\nscore: 90\nreason: new\ntime: 2026-01-02\npain_event_id: 7\n', 'utf8');
+
+        // clearPainFlag with expected id=5 should NOT delete the new signal (id=7)
+        clearPainFlag(workspaceDir, 5);
+        expect(fs.existsSync(painFlagPath)).toBe(true);
+
+        // The file should still contain the new signal
+        const remaining = fs.readFileSync(painFlagPath, 'utf8');
+        expect(remaining).toContain('pain_event_id: 7');
+    });
+
+    it('should delete file when expectedPainEventId matches', () => {
+        fs.writeFileSync(painFlagPath, 'source: test\nscore: 80\nreason: idem\ntime: 2026-01-01\npain_event_id: 42\n', 'utf8');
+        expect(fs.existsSync(painFlagPath)).toBe(true);
+        clearPainFlag(workspaceDir, 42);
+        expect(fs.existsSync(painFlagPath)).toBe(false);
+    });
+});