principles-disciple 1.52.0 → 1.54.0

package/tests/core/nocturnal-trinity.test.ts

@@ -12,6 +12,7 @@ import {
   formatReasoningContext,
   invokeStubDreamer,
   invokeStubPhilosopher,
+  validateExtraction,
   type TrinityConfig,
   type DreamerOutput,
   type DreamerCandidate,
@@ -1815,3 +1816,238 @@ describe('Scribe Backward Compatibility (SCRIBE-04)', () => {
     expect(result.artifact!.chosenJustification).toBeUndefined();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Tests: validateExtraction — Hallucination Detection (SDK-QUAL-02)
+// ---------------------------------------------------------------------------
+
+describe('validateExtraction — Hallucination Detection (SDK-QUAL-02)', () => {
+  function makeArtifact(badDecision: string, overrides: Record<string, unknown> = {}): TrinityDraftArtifact {
+    return {
+      selectedCandidateIndex: 0,
+      badDecision,
+      betterDecision: 'Do it right instead',
+      rationale: 'Because the principle says so and this is the correct approach',
+      sessionId: 'session-test-123',
+      principleId: 'T-01',
+      sourceSnapshotRef: 'snapshot-test-001',
+      telemetry: {
+        chainMode: 'trinity',
+        usedStubs: true,
+        dreamerPassed: true,
+        philosopherPassed: true,
+        scribePassed: true,
+        candidateCount: 1,
+        selectedCandidateIndex: 0,
+        stageFailures: [],
+      },
+      ...overrides,
+    };
+  }
+
+  function makeSnapshotWithEvidence(overrides: {
+    failedToolCalls?: Array<{ toolName: string; filePath?: string; errorMessage?: string }>;
+    painEvents?: Array<{ source: string; score: number; reason?: string }>;
+    gateBlocks?: Array<{ toolName: string; reason: string }>;
+    userCorrections?: number;
+  } = {}) {
+    const toolCalls = (overrides.failedToolCalls ?? []).map(tc => ({
+      toolName: tc.toolName,
+      outcome: 'failure' as const,
+      filePath: tc.filePath ?? null,
+      durationMs: null,
+      exitCode: 1,
+      errorType: 'runtime_error',
+      errorMessage: tc.errorMessage ?? 'unknown error',
+      createdAt: '2026-04-17T00:00:00.000Z',
+    }));
+
+    const painEvents = (overrides.painEvents ?? []).map(pe => ({
+      source: pe.source,
+      score: pe.score,
+      severity: 'medium' as const,
+      reason: pe.reason ?? null,
+      createdAt: '2026-04-17T00:00:00.000Z',
+    }));
+
+    const gateBlocks = (overrides.gateBlocks ?? []).map(gb => ({
+      toolName: gb.toolName,
+      filePath: null,
+      reason: gb.reason,
+      planStatus: null,
+      createdAt: '2026-04-17T00:00:00.000Z',
+    }));
+
+    const userTurns = Array.from({ length: overrides.userCorrections ?? 0 }, (_, i) => ({
+      turnIndex: i,
+      correctionDetected: true,
+      correctionCue: 'wrong approach',
+      createdAt: '2026-04-17T00:00:00.000Z',
+    }));
+
+    return {
+      sessionId: 'session-test-123',
+      startedAt: '2026-04-17T00:00:00.000Z',
+      updatedAt: '2026-04-17T00:05:00.000Z',
+      assistantTurns: [],
+      userTurns,
+      toolCalls: toolCalls,
+      painEvents,
+      gateBlocks,
+      stats: {
+        failureCount: toolCalls.length,
+        totalPainEvents: painEvents.length,
+        totalGateBlocks: gateBlocks.length,
+        totalAssistantTurns: 5,
+        totalToolCalls: 10,
+      },
+    };
+  }
+
+  it('passes when badDecision references a tool failure from the snapshot', () => {
+    const snapshot = makeSnapshotWithEvidence({
+      failedToolCalls: [{ toolName: 'Edit', filePath: 'src/config.ts', errorMessage: 'permission denied' }],
+    });
+    const artifact = makeArtifact('Proceeded with Edit on src/config.ts without checking permission');
+
+    const result = validateExtraction(artifact, snapshot as any);
+
+    expect(result.isGrounded).toBe(true);
+    expect(result.evidenceTypes).toContain('tool_failures');
+  });
+
+  it('passes when badDecision references a pain event from the snapshot', () => {
+    const snapshot = makeSnapshotWithEvidence({
+      painEvents: [{ source: 'gate', score: 70, reason: 'accumulated friction from repeated file operation failures' }],
+    });
+    const artifact = makeArtifact('Ignored accumulated friction from file operations');
+
+    const result = validateExtraction(artifact, snapshot as any);
+
+    expect(result.isGrounded).toBe(true);
+    expect(result.evidenceTypes).toContain('pain_events');
+  });
+
+  it('passes when badDecision references a gate block from the snapshot', () => {
+    const snapshot = makeSnapshotWithEvidence({
+      gateBlocks: [{ toolName: 'Bash', reason: 'destructive command blocked by safety gate' }],
+    });
+    const artifact = makeArtifact('Attempted to execute a destructive Bash command that was blocked by the gate');
+
+    const result = validateExtraction(artifact, snapshot as any);
+
+    expect(result.isGrounded).toBe(true);
+    expect(result.evidenceTypes).toContain('gate_blocks');
+  });
+
+  it('passes when badDecision references user corrections', () => {
+    const snapshot = makeSnapshotWithEvidence({
+      userCorrections: 2,
+    });
+    const artifact = makeArtifact('Continued with the wrong approach despite user corrections');
+
+    const result = validateExtraction(artifact, snapshot as any);
+
+    expect(result.isGrounded).toBe(true);
+    expect(result.evidenceTypes).toContain('user_corrections');
+  });
+
+  it('detects hallucination when badDecision has no overlap with snapshot evidence', () => {
+    const snapshot = makeSnapshotWithEvidence({
+      failedToolCalls: [{ toolName: 'Read', filePath: 'package.json', errorMessage: 'file not found' }],
+    });
+    const artifact = makeArtifact('Deployed production database without running migration scripts first');
+
+    const result = validateExtraction(artifact, snapshot as any);
+
+    expect(result.isGrounded).toBe(false);
+    expect(result.reason).toContain('Hallucinated extraction');
+  });
+
+  it('passes when snapshot has no evidence at all (no signal to validate against)', () => {
+    const snapshot = makeSnapshotWithEvidence();
+    const artifact = makeArtifact('Made an incorrect decision during the session');
+
+    const result = validateExtraction(artifact, snapshot as any);
+
+    // No evidence means we cannot validate -- allow through
+    expect(result.isGrounded).toBe(true);
+    expect(result.evidenceTypes).toHaveLength(0);
+  });
+
+  it('provides evidence preview for telemetry', () => {
+    const snapshot = makeSnapshotWithEvidence({
+      failedToolCalls: [{ toolName: 'Write', filePath: 'output.log', errorMessage: 'permission denied for write operation' }],
+      painEvents: [{ source: 'hook', score: 80, reason: 'repeated permission denied failures during write operation' }],
+    });
+    const artifact = makeArtifact('Proceeded with write operation on output.log despite permission denied error');
+
+    const result = validateExtraction(artifact, snapshot as any);
+
+    expect(result.isGrounded).toBe(true);
+    expect(result.evidencePreview.length).toBeGreaterThan(0);
+    expect(result.evidenceTypes).toContain('tool_failures');
+    expect(result.evidenceTypes).toContain('pain_events');
+  });
+
+  it('detects hallucination with unrelated but specific badDecision text', () => {
+    const snapshot = makeSnapshotWithEvidence({
+      painEvents: [{ source: 'gate', score: 60, reason: 'rate limit exceeded for API calls' }],
+    });
+    const artifact = makeArtifact('Deleted the primary database without creating a backup first');
+
+    const result = validateExtraction(artifact, snapshot as any);
+
+    expect(result.isGrounded).toBe(false);
+  });
+
+  it('runTrinity stub path fails when hallucination is detected', () => {
+    // Create a snapshot with failure signals so stub candidates are generated
+    // but override the tool calls to be something completely unrelated to what
+    // the stub Dreamer generates (which mentions "failing operation")
+    const snapshot = {
+      sessionId: 'session-hallucination-test',
+      startedAt: '2026-04-17T00:00:00.000Z',
+      updatedAt: '2026-04-17T00:05:00.000Z',
+      assistantTurns: [],
+      userTurns: [],
+      toolCalls: [
+        {
+          toolName: 'Grep',
+          outcome: 'failure' as const,
+          filePath: null,
+          durationMs: null,
+          exitCode: 1,
+          errorType: 'timeout',
+          errorMessage: 'search timed out after 30 seconds',
+          createdAt: '2026-04-17T00:00:00.000Z',
+        },
+      ],
+      painEvents: [],
+      gateBlocks: [],
+      stats: {
+        failureCount: 1,
+        totalPainEvents: 0,
+        totalGateBlocks: 0,
+        totalAssistantTurns: 2,
+        totalToolCalls: 1,
+      },
+    };
+
+    const config: TrinityConfig = {
+      useTrinity: true,
+      maxCandidates: 3,
+      useStubs: true,
+    };
+
+    const result = runTrinity({ snapshot: snapshot as any, principleId: 'T-08', config });
+
+    // The stub Dreamer generates candidates mentioning "failing operation" and "config.json"
+    // The snapshot has a Grep failure with "search timed out"
+    // With the normalized token matching: badDecisionTokens = {retry,faili,oper,diagnos,root,caus}
+    // and evidenceTokens = {search,timed,after,seconds,timedout} — no overlap → extraction fails
+    // So result.success must be false with a Hallucinated failure.
+    expect(result.success).toBe(false);
+    expect(result.failures.some(f => f.reason?.includes('Hallucinated'))).toBe(true);
+  });
+});

package/tests/core/observability.test.ts

@@ -0,0 +1,383 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { calculateBaselines } from '../../src/core/observability.js';
+import type { ObservabilityBaselines } from '../../src/core/observability.js';
+import { loadLedger, saveLedger } from '../../src/core/principle-tree-ledger.js';
+import type { HybridLedgerStore } from '../../src/core/principle-tree-ledger.js';
+import { safeRmDir } from '../test-utils.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'pd-observability-test-'));
+}
+
+function createEmptyStore(): HybridLedgerStore {
+  return {
+    trainingStore: {},
+    tree: {
+      principles: {},
+      rules: {},
+      implementations: {},
+      metrics: {},
+      lastUpdated: new Date(0).toISOString(),
+    },
+  };
+}
+
+function createTestPrinciple(id: string, status: string, priority: string) {
+  return {
+    id,
+    version: 1,
+    text: `Test principle ${id}`,
+    triggerPattern: 'test',
+    action: 'verify',
+    status,
+    priority,
+    scope: 'general',
+    evaluability: 'manual_only' as const,
+    valueScore: 0,
+    adherenceRate: 0,
+    painPreventedCount: 0,
+    derivedFromPainIds: [] as string[],
+    ruleIds: [] as string[],
+    conflictsWithPrincipleIds: [] as string[],
+    createdAt: '2026-04-17T00:00:00.000Z',
+    updatedAt: '2026-04-17T00:00:00.000Z',
+  };
+}
+
+function seedStore(stateDir: string, store: HybridLedgerStore): void {
+  saveLedger(stateDir, store);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('calculateBaselines', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = createTmpDir();
+    seedStore(tmpDir, createEmptyStore());
+  });
+
+  afterEach(() => {
+    safeRmDir(tmpDir);
+  });
+
+  // -------------------------------------------------------------------------
+  // Empty state
+  // -------------------------------------------------------------------------
+
+  it('returns zeros for empty store', () => {
+    const baselines = calculateBaselines(tmpDir);
+
+    expect(baselines.principleStock).toBe(0);
+    expect(baselines.totalRules).toBe(0);
+    expect(baselines.totalImplementations).toBe(0);
+    expect(baselines.avgRulesPerPrinciple).toBe(0);
+    expect(baselines.avgImplementationsPerRule).toBe(0);
+    expect(baselines.totalPainEvents).toBe(0);
+    expect(baselines.associationRate).toBe(0);
+    expect(baselines.internalizedCount).toBe(0);
+    expect(baselines.internalizationRate).toBe(0);
+  });
+
+  it('sets calculatedAt to current time', () => {
+    const before = new Date().toISOString();
+    const baselines = calculateBaselines(tmpDir);
+    const after = new Date().toISOString();
+
+    expect(baselines.calculatedAt >= before).toBe(true);
+    expect(baselines.calculatedAt <= after).toBe(true);
+  });
+
+  // -------------------------------------------------------------------------
+  // Principle Stock
+  // -------------------------------------------------------------------------
+
+  it('counts all principles in the ledger', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    store.tree.principles['P-002'] = createTestPrinciple('P-002', 'candidate', 'P2');
+    store.tree.principles['P-003'] = createTestPrinciple('P-003', 'deprecated', 'P1');
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.principleStock).toBe(3);
+  });
+
+  // -------------------------------------------------------------------------
+  // Structure
+  // -------------------------------------------------------------------------
+
+  it('calculates avgRulesPerPrinciple', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = {
+      ...createTestPrinciple('P-001', 'active', 'P1'),
+      ruleIds: ['R-001', 'R-002'],
+    };
+    store.tree.principles['P-002'] = {
+      ...createTestPrinciple('P-002', 'active', 'P1'),
+      ruleIds: ['R-003'],
+    };
+    store.tree.rules['R-001'] = { id: 'R-001', principleId: 'P-001', implementationIds: [] } as any;
+    store.tree.rules['R-002'] = { id: 'R-002', principleId: 'P-001', implementationIds: [] } as any;
+    store.tree.rules['R-003'] = { id: 'R-003', principleId: 'P-002', implementationIds: [] } as any;
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.totalRules).toBe(3);
+    expect(baselines.avgRulesPerPrinciple).toBe(1.5); // 3 rules / 2 principles
+  });
+
+  it('calculates avgImplementationsPerRule', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = {
+      ...createTestPrinciple('P-001', 'active', 'P1'),
+      ruleIds: ['R-001'],
+    };
+    store.tree.rules['R-001'] = {
+      id: 'R-001',
+      principleId: 'P-001',
+      implementationIds: ['I-001', 'I-002'],
+    } as any;
+    store.tree.implementations['I-001'] = { id: 'I-001', ruleId: 'R-001' } as any;
+    store.tree.implementations['I-002'] = { id: 'I-002', ruleId: 'R-001' } as any;
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.totalImplementations).toBe(2);
+    expect(baselines.avgImplementationsPerRule).toBe(2); // 2 impls / 1 rule
+  });
+
+  it('returns 0 for structure metrics when no principles exist', () => {
+    seedStore(tmpDir, createEmptyStore());
+    const baselines = calculateBaselines(tmpDir);
+
+    expect(baselines.avgRulesPerPrinciple).toBe(0);
+    expect(baselines.avgImplementationsPerRule).toBe(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // Association Rate
+  // -------------------------------------------------------------------------
+
+  it('returns 0 association rate when no pain events exist', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.totalPainEvents).toBe(0);
+    expect(baselines.associationRate).toBe(0);
+  });
+
+  it('computes association rate as principles / pain events', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    store.tree.principles['P-002'] = createTestPrinciple('P-002', 'active', 'P2');
+    seedStore(tmpDir, store);
+
+    // Create a trajectory DB with pain events
+    const dbPath = path.join(tmpDir, 'trajectory.db');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const Database = require('better-sqlite3');
+    const db = new Database(dbPath);
+    db.exec(`
+      CREATE TABLE pain_events (id TEXT PRIMARY KEY, created_at TEXT);
+      INSERT INTO pain_events VALUES ('pe-1', '2026-04-17T00:00:00Z');
+      INSERT INTO pain_events VALUES ('pe-2', '2026-04-17T00:01:00Z');
+      INSERT INTO pain_events VALUES ('pe-3', '2026-04-17T00:02:00Z');
+      INSERT INTO pain_events VALUES ('pe-4', '2026-04-17T00:03:00Z');
+    `);
+    db.close();
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.totalPainEvents).toBe(4);
+    expect(baselines.associationRate).toBe(0.5); // 2 principles / 4 pain events
+  });
+
+  // -------------------------------------------------------------------------
+  // Internalization Rate
+  // -------------------------------------------------------------------------
+
+  it('computes internalization rate from training store', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    store.tree.principles['P-002'] = createTestPrinciple('P-002', 'active', 'P2');
+    store.tree.principles['P-003'] = createTestPrinciple('P-003', 'candidate', 'P2');
+    store.trainingStore['P-001'] = {
+      principleId: 'P-001',
+      evaluability: 'deterministic',
+      applicableOpportunityCount: 10,
+      observedViolationCount: 0,
+      complianceRate: 1.0,
+      violationTrend: 0,
+      generatedSampleCount: 5,
+      approvedSampleCount: 5,
+      includedTrainRunIds: ['run-1'],
+      deployedCheckpointIds: ['ckpt-1'],
+      internalizationStatus: 'internalized',
+    };
+    store.trainingStore['P-002'] = {
+      principleId: 'P-002',
+      evaluability: 'weak_heuristic',
+      applicableOpportunityCount: 3,
+      observedViolationCount: 1,
+      complianceRate: 0.67,
+      violationTrend: 0,
+      generatedSampleCount: 0,
+      approvedSampleCount: 0,
+      includedTrainRunIds: [],
+      deployedCheckpointIds: [],
+      internalizationStatus: 'in_training',
+    };
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.internalizedCount).toBe(1);
+    // 1 internalized / 3 total principles = 0.333
+    expect(baselines.internalizationRate).toBeGreaterThan(0.33);
+    expect(baselines.internalizationRate).toBeLessThanOrEqual(0.334);
+  });
+
+  it('returns 0 internalization rate when no principles are internalized', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    store.trainingStore['P-001'] = {
+      principleId: 'P-001',
+      evaluability: 'manual_only',
+      applicableOpportunityCount: 0,
+      observedViolationCount: 0,
+      complianceRate: 0,
+      violationTrend: 0,
+      generatedSampleCount: 0,
+      approvedSampleCount: 0,
+      includedTrainRunIds: [],
+      deployedCheckpointIds: [],
+      internalizationStatus: 'prompt_only',
+    };
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.internalizedCount).toBe(0);
+    expect(baselines.internalizationRate).toBe(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // Distributions
+  // -------------------------------------------------------------------------
+
+  it('computes status distribution', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    store.tree.principles['P-002'] = createTestPrinciple('P-002', 'active', 'P2');
+    store.tree.principles['P-003'] = createTestPrinciple('P-003', 'candidate', 'P1');
+    store.tree.principles['P-004'] = createTestPrinciple('P-004', 'deprecated', 'P2');
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.statusDistribution.active).toBe(2);
+    expect(baselines.statusDistribution.candidate).toBe(1);
+    expect(baselines.statusDistribution.deprecated).toBe(1);
+  });
+
+  it('computes priority distribution', () => {
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P0');
+    store.tree.principles['P-002'] = createTestPrinciple('P-002', 'active', 'P1');
+    store.tree.principles['P-003'] = createTestPrinciple('P-003', 'active', 'P1');
+    store.tree.principles['P-004'] = createTestPrinciple('P-004', 'active', 'P2');
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.priorityDistribution.P0).toBe(1);
+    expect(baselines.priorityDistribution.P1).toBe(2);
+    expect(baselines.priorityDistribution.P2).toBe(1);
+  });
+
+  it('computes internalization distribution', () => {
+    const store = createEmptyStore();
+    store.trainingStore['p-1'] = {
+      principleId: 'p-1',
+      evaluability: 'deterministic',
+      applicableOpportunityCount: 5,
+      observedViolationCount: 0,
+      complianceRate: 1.0,
+      violationTrend: 0,
+      generatedSampleCount: 3,
+      approvedSampleCount: 3,
+      includedTrainRunIds: [],
+      deployedCheckpointIds: [],
+      internalizationStatus: 'internalized',
+    };
+    store.trainingStore['p-2'] = {
+      principleId: 'p-2',
+      evaluability: 'manual_only',
+      applicableOpportunityCount: 0,
+      observedViolationCount: 0,
+      complianceRate: 0,
+      violationTrend: 0,
+      generatedSampleCount: 0,
+      approvedSampleCount: 0,
+      includedTrainRunIds: [],
+      deployedCheckpointIds: [],
+      internalizationStatus: 'prompt_only',
+    };
+    seedStore(tmpDir, store);
+
+    const baselines = calculateBaselines(tmpDir);
+    expect(baselines.internalizationDistribution.internalized).toBe(1);
+    expect(baselines.internalizationDistribution.prompt_only).toBe(1);
+  });
+
+  // -------------------------------------------------------------------------
+  // Persistence
+  // -------------------------------------------------------------------------
+
+  it('persists baselines to .state/baselines.json', () => {
+    calculateBaselines(tmpDir);
+
+    const baselinesPath = path.join(tmpDir, 'baselines.json');
+    expect(fs.existsSync(baselinesPath)).toBe(true);
+
+    const raw = JSON.parse(fs.readFileSync(baselinesPath, 'utf8')) as ObservabilityBaselines;
+    expect(raw.principleStock).toBe(0);
+    expect(raw.calculatedAt).toBeDefined();
+  });
+
+  it('overwrites previous baselines on recalculation', () => {
+    // First calculation with empty store
+    calculateBaselines(tmpDir);
+
+    // Add a principle
+    const store = createEmptyStore();
+    store.tree.principles['P-001'] = createTestPrinciple('P-001', 'active', 'P1');
+    seedStore(tmpDir, store);
+
+    // Second calculation
+    calculateBaselines(tmpDir);
+
+    const baselinesPath = path.join(tmpDir, 'baselines.json');
+    const raw = JSON.parse(fs.readFileSync(baselinesPath, 'utf8')) as ObservabilityBaselines;
+    expect(raw.principleStock).toBe(1);
+  });
+
+  // -------------------------------------------------------------------------
+  // Edge cases
+  // -------------------------------------------------------------------------
+
+  it('handles missing state directory gracefully', () => {
+    const missingDir = path.join(tmpDir, 'nonexistent');
+    // loadLedger handles missing dirs by returning empty store
+    const baselines = calculateBaselines(missingDir);
+    expect(baselines.principleStock).toBe(0);
+  });
+});

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');
+    });
+});