principles-disciple 1.52.0 → 1.54.0

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

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import type { PainSignalAdapter } from '../../src/core/pain-signal-adapter.js';
+import type { PainSignal } from '../../src/core/pain-signal.js';
+import { validatePainSignal } from '../../src/core/pain-signal.js';
+
+// ---------------------------------------------------------------------------
+// Mock Framework Event
+// ---------------------------------------------------------------------------
+
+/** Simulated framework-specific event for testing */
+interface MockToolCallEvent {
+  toolName: string;
+  success: boolean;
+  errorMessage?: string;
+  sessionId: string;
+  agentId: string;
+  timestamp: string;
+}
+
+// ---------------------------------------------------------------------------
+// Test Adapter Implementation
+// ---------------------------------------------------------------------------
+
+/** Test adapter that translates MockToolCallEvent to PainSignal */
+const mockAdapter: PainSignalAdapter<MockToolCallEvent> = {
+  capture(event: MockToolCallEvent): PainSignal | null {
+    // Per D-02: pure translation. Only failed tool calls produce signals.
+    if (event.success) return null;
+
+    // Return null for malformed events
+    if (!event.toolName || !event.errorMessage) return null;
+
+    return {
+      source: 'tool_failure',
+      score: 75,
+      timestamp: event.timestamp,
+      reason: `Tool ${event.toolName} failed: ${event.errorMessage}`,
+      sessionId: event.sessionId,
+      agentId: event.agentId,
+      traceId: `test-${Date.now()}`,
+      triggerTextPreview: event.errorMessage.slice(0, 100),
+      domain: 'coding',
+      severity: 'high',
+      context: { toolName: event.toolName },
+    };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function mockToolFailure(overrides: Partial<MockToolCallEvent> = {}): MockToolCallEvent {
+  return {
+    toolName: 'edit_file',
+    success: false,
+    errorMessage: 'File not found: test.ts',
+    sessionId: 'session-001',
+    agentId: 'main',
+    timestamp: '2026-04-17T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('PainSignalAdapter', () => {
+  it('captures a failed tool call as PainSignal', () => {
+    const result = mockAdapter.capture(mockToolFailure());
+    expect(result).not.toBeNull();
+    expect(result!.source).toBe('tool_failure');
+  });
+
+  it('returns null for successful tool calls', () => {
+    const result = mockAdapter.capture({ success: true } as MockToolCallEvent);
+    expect(result).toBeNull();
+  });
+
+  it('returns null for malformed events missing toolName', () => {
+    const result = mockAdapter.capture({
+      success: false,
+      toolName: '',
+      errorMessage: 'err',
+      sessionId: 's-1',
+      agentId: 'a-1',
+      timestamp: '2026-04-17T00:00:00.000Z',
+    });
+    expect(result).toBeNull();
+  });
+
+  it('returns null for malformed events missing errorMessage', () => {
+    const result = mockAdapter.capture({
+      success: false,
+      toolName: 'edit',
+      errorMessage: undefined,
+      sessionId: 's-1',
+      agentId: 'a-1',
+      timestamp: '2026-04-17T00:00:00.000Z',
+    });
+    expect(result).toBeNull();
+  });
+
+  it('produces signals that pass validatePainSignal', () => {
+    const signal = mockAdapter.capture(mockToolFailure());
+    expect(signal).not.toBeNull();
+    const result = validatePainSignal(signal!);
+    expect(result.valid).toBe(true);
+  });
+
+  it('satisfies the PainSignalAdapter interface type contract', () => {
+    const adapter: PainSignalAdapter<MockToolCallEvent> = mockAdapter;
+    expect(typeof adapter.capture).toBe('function');
+  });
+});

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

@@ -0,0 +1,190 @@
+import { describe, it, expect } from 'vitest';
+import {
+  PainSignalSchema,
+  validatePainSignal,
+  deriveSeverity,
+  type PainSignal,
+} from '../../src/core/pain-signal.js';
+import { Value } from '@sinclair/typebox/value';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Produces a valid minimal PainSignal object. */
+function validSignal(overrides: Partial<PainSignal> = {}): PainSignal {
+  return {
+    source: 'tool_failure',
+    score: 75,
+    timestamp: '2026-04-17T00:00:00.000Z',
+    reason: 'Build failed with exit code 1',
+    sessionId: 'session-001',
+    agentId: 'main',
+    traceId: 'trace-abc',
+    triggerTextPreview: 'npm run build',
+    domain: 'coding',
+    severity: 'high',
+    context: {},
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// PainSignalSchema
+// ---------------------------------------------------------------------------
+
+describe('PainSignalSchema', () => {
+  it('accepts a valid signal', () => {
+    const signal = validSignal();
+    expect(Value.Check(PainSignalSchema, signal)).toBe(true);
+  });
+
+  it('rejects signal with missing required source', () => {
+    const signal = validSignal();
+    delete (signal as Record<string, unknown>).source;
+    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+  });
+
+  it('rejects signal with missing required reason', () => {
+    const signal = validSignal();
+    delete (signal as Record<string, unknown>).reason;
+    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+  });
+
+  it('rejects score below 0', () => {
+    const signal = validSignal({ score: -1 });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+  });
+
+  it('rejects score above 100', () => {
+    const signal = validSignal({ score: 101 });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+  });
+
+  it('rejects empty source string', () => {
+    const signal = validSignal({ source: '' });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(false);
+  });
+
+  it('accepts empty optional fields (sessionId, agentId, etc.)', () => {
+    const signal = validSignal({
+      sessionId: '',
+      agentId: '',
+      traceId: '',
+      triggerTextPreview: '',
+    });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(true);
+  });
+
+  it('accepts any string for domain', () => {
+    const signal = validSignal({ domain: 'writing' });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(true);
+  });
+
+  it('accepts context with mixed value types', () => {
+    const signal = validSignal({ context: { filePath: '/src/index.ts', lineCount: 42 } });
+    expect(Value.Check(PainSignalSchema, signal)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// deriveSeverity
+// ---------------------------------------------------------------------------
+
+describe('deriveSeverity', () => {
+  it('returns "low" for scores 0-39', () => {
+    expect(deriveSeverity(0)).toBe('low');
+    expect(deriveSeverity(20)).toBe('low');
+    expect(deriveSeverity(39)).toBe('low');
+  });
+
+  it('returns "medium" for scores 40-69', () => {
+    expect(deriveSeverity(40)).toBe('medium');
+    expect(deriveSeverity(55)).toBe('medium');
+    expect(deriveSeverity(69)).toBe('medium');
+  });
+
+  it('returns "high" for scores 70-89', () => {
+    expect(deriveSeverity(70)).toBe('high');
+    expect(deriveSeverity(80)).toBe('high');
+    expect(deriveSeverity(89)).toBe('high');
+  });
+
+  it('returns "critical" for scores 90-100', () => {
+    expect(deriveSeverity(90)).toBe('critical');
+    expect(deriveSeverity(95)).toBe('critical');
+    expect(deriveSeverity(100)).toBe('critical');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validatePainSignal
+// ---------------------------------------------------------------------------
+
+describe('validatePainSignal', () => {
+  it('validates a correct signal and returns it typed', () => {
+    const input = validSignal();
+    const result = validatePainSignal(input);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+    expect(result.signal).toEqual(input);
+  });
+
+  it('fills default domain when missing', () => {
+    const input = validSignal();
+    delete (input as Record<string, unknown>).domain;
+    const result = validatePainSignal(input);
+    expect(result.valid).toBe(true);
+    expect(result.signal?.domain).toBe('coding');
+  });
+
+  it('fills default severity from score when missing', () => {
+    const input = validSignal({ score: 45 });
+    delete (input as Record<string, unknown>).severity;
+    const result = validatePainSignal(input);
+    expect(result.valid).toBe(true);
+    expect(result.signal?.severity).toBe('medium');
+  });
+
+  it('fills default context when missing', () => {
+    const input = validSignal();
+    delete (input as Record<string, unknown>).context;
+    const result = validatePainSignal(input);
+    expect(result.valid).toBe(true);
+    expect(result.signal?.context).toEqual({});
+  });
+
+  it('rejects non-object input', () => {
+    const result = validatePainSignal('not an object');
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Input must be a non-null object');
+  });
+
+  it('rejects null input', () => {
+    const result = validatePainSignal(null);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Input must be a non-null object');
+  });
+
+  it('rejects array input', () => {
+    const result = validatePainSignal([1, 2, 3]);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('Input must be a non-null object');
+  });
+
+  it('reports errors for missing required fields', () => {
+    const result = validatePainSignal({});
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  it('rejects invalid score type', () => {
+    const result = validatePainSignal({ ...validSignal(), score: 'high' });
+    expect(result.valid).toBe(false);
+  });
+
+  it('rejects invalid severity value', () => {
+    const result = validatePainSignal({ ...validSignal(), severity: 'extreme' });
+    expect(result.valid).toBe(false);
+  });
+});

package/tests/core/principle-injection.test.ts

@@ -0,0 +1,223 @@
+import { describe, it, expect } from 'vitest';
+import {
+  selectPrinciplesForInjection,
+  formatPrinciple,
+  DEFAULT_PRINCIPLE_BUDGET,
+  type InjectablePrinciple,
+  type PrincipleSelectionResult,
+} from '../../src/core/principle-injection.js';
+import type { PrinciplePriority } from '../../src/types/principle-tree-schema.js';
+
+// ---------------------------------------------------------------------------
+// Test Fixtures
+// ---------------------------------------------------------------------------
+
+function makePrinciple(overrides: Partial<{
+  id: string;
+  text: string;
+  priority: PrinciplePriority;
+  createdAt: string;
+}> = {}): InjectablePrinciple {
+  return {
+    id: overrides.id ?? 'P_001',
+    text: overrides.text ?? 'Always verify file content before editing',
+    priority: overrides.priority ?? 'P1',
+    createdAt: overrides.createdAt ?? '2026-04-01T00:00:00.000Z',
+  };
+}
+
+function makePrinciples(configs: Array<{ id: string; priority: PrinciplePriority; text?: string; createdAt?: string }>): InjectablePrinciple[] {
+  return configs.map(c => makePrinciple({
+    id: c.id,
+    priority: c.priority,
+    text: c.text ?? `Principle ${c.id}`,
+    createdAt: c.createdAt ?? '2026-04-01T00:00:00.000Z',
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Tests: formatPrinciple
+// ---------------------------------------------------------------------------
+
+describe('formatPrinciple', () => {
+  it('formats a principle as "- [ID] text"', () => {
+    const p = makePrinciple({ id: 'P_001', text: 'Always verify before editing' });
+    expect(formatPrinciple(p)).toBe('- [P_001] Always verify before editing');
+  });
+
+  it('includes the full text even when long', () => {
+    const longText = 'A'.repeat(200);
+    const p = makePrinciple({ id: 'P_100', text: longText });
+    expect(formatPrinciple(p)).toBe(`- [P_100] ${longText}`);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: selectPrinciplesForInjection — priority ordering
+// ---------------------------------------------------------------------------
+
+describe('selectPrinciplesForInjection — priority ordering', () => {
+  it('selects P0 principles before P1 and P2', () => {
+    const principles = makePrinciples([
+      { id: 'P1', priority: 'P2' },
+      { id: 'P2', priority: 'P0' },
+      { id: 'P3', priority: 'P1' },
+    ]);
+
+    const result = selectPrinciplesForInjection(principles, 10000);
+
+    expect(result.selected[0].id).toBe('P2'); // P0 first
+    expect(result.selected[1].id).toBe('P3'); // P1 second
+    expect(result.selected[2].id).toBe('P1'); // P2 third
+  });
+
+  it('selects newer principles first within same priority', () => {
+    const principles = makePrinciples([
+      { id: 'OLD', priority: 'P1', createdAt: '2026-03-01T00:00:00.000Z' },
+      { id: 'NEW', priority: 'P1', createdAt: '2026-04-15T00:00:00.000Z' },
+    ]);
+
+    const result = selectPrinciplesForInjection(principles, 10000);
+
+    expect(result.selected[0].id).toBe('NEW'); // Newer first
+    expect(result.selected[1].id).toBe('OLD');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: selectPrinciplesForInjection — budget enforcement
+// ---------------------------------------------------------------------------
+
+describe('selectPrinciplesForInjection — budget enforcement', () => {
+  it('respects the character budget', () => {
+    const principles = makePrinciples(
+      Array.from({ length: 20 }, (_, i) => ({
+        id: `P_${String(i).padStart(3, '0')}`,
+        priority: 'P1' as PrinciplePriority,
+        text: `Principle with a reasonably long text description number ${i}`,
+      }))
+    );
+
+    const budget = 500;
+    const result = selectPrinciplesForInjection(principles, budget);
+
+    expect(result.totalChars).toBeLessThanOrEqual(budget + 200); // Allow some slack for P0 force-include
+    expect(result.selected.length).toBeLessThan(20);
+    expect(result.wasTruncated).toBe(true);
+  });
+
+  it('includes all principles when budget is large enough', () => {
+    const principles = makePrinciples([
+      { id: 'P_001', priority: 'P0' },
+      { id: 'P_002', priority: 'P1' },
+      { id: 'P_003', priority: 'P2' },
+    ]);
+
+    const result = selectPrinciplesForInjection(principles, 10000);
+
+    expect(result.selected).toHaveLength(3);
+    expect(result.wasTruncated).toBe(false);
+  });
+
+  it('returns empty selection for empty principles array', () => {
+    const result = selectPrinciplesForInjection([], 10000);
+
+    expect(result.selected).toHaveLength(0);
+    expect(result.totalChars).toBe(0);
+    expect(result.hasP0).toBe(false);
+    expect(result.wasTruncated).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: selectPrinciplesForInjection — P0 guarantee
+// ---------------------------------------------------------------------------
+
+describe('selectPrinciplesForInjection — P0 guarantee', () => {
+  it('ensures at least one P0 principle is included even when over budget', () => {
+    // Fill budget with P1 principles, then have a P0 that would exceed budget
+    const principles: InjectablePrinciple[] = [];
+
+    // Add many P1 principles that fill the budget
+    for (let i = 0; i < 10; i++) {
+      principles.push(makePrinciple({
+        id: `P1_${i}`,
+        priority: 'P1',
+        text: `P1 principle with enough text to consume budget space ${i}`,
+        createdAt: '2026-04-01T00:00:00.000Z',
+      }));
+    }
+
+    // Add a P0 principle
+    principles.push(makePrinciple({
+      id: 'P0_CRITICAL',
+      priority: 'P0',
+      text: 'Critical P0 principle that must always be included',
+      createdAt: '2026-04-01T00:00:00.000Z',
+    }));
+
+    const budget = 200; // Very small budget
+    const result = selectPrinciplesForInjection(principles, budget);
+
+    expect(result.hasP0).toBe(true);
+    expect(result.selected.some(p => p.priority === 'P0')).toBe(true);
+  });
+
+  it('sets hasP0=true when P0 principles are naturally selected', () => {
+    const principles = makePrinciples([
+      { id: 'P0_1', priority: 'P0' },
+      { id: 'P1_1', priority: 'P1' },
+    ]);
+
+    const result = selectPrinciplesForInjection(principles, 10000);
+
+    expect(result.hasP0).toBe(true);
+    expect(result.breakdown.p0).toBe(1);
+  });
+
+  it('sets hasP0=false when no P0 principles exist', () => {
+    const principles = makePrinciples([
+      { id: 'P1_1', priority: 'P1' },
+      { id: 'P2_1', priority: 'P2' },
+    ]);
+
+    const result = selectPrinciplesForInjection(principles, 10000);
+
+    expect(result.hasP0).toBe(false);
+    expect(result.breakdown.p0).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: selectPrinciplesForInjection — breakdown
+// ---------------------------------------------------------------------------
+
+describe('selectPrinciplesForInjection — breakdown', () => {
+  it('counts principles by priority tier correctly', () => {
+    const principles = makePrinciples([
+      { id: 'P0_1', priority: 'P0' },
+      { id: 'P0_2', priority: 'P0' },
+      { id: 'P1_1', priority: 'P1' },
+      { id: 'P1_2', priority: 'P1' },
+      { id: 'P1_3', priority: 'P1' },
+      { id: 'P2_1', priority: 'P2' },
+    ]);
+
+    const result = selectPrinciplesForInjection(principles, 10000);
+
+    expect(result.breakdown.p0).toBe(2);
+    expect(result.breakdown.p1).toBe(3);
+    expect(result.breakdown.p2).toBe(1);
+    expect(result.selected).toHaveLength(6);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: DEFAULT_PRINCIPLE_BUDGET
+// ---------------------------------------------------------------------------
+
+describe('DEFAULT_PRINCIPLE_BUDGET', () => {
+  it('is set to 4000 characters', () => {
+    expect(DEFAULT_PRINCIPLE_BUDGET).toBe(4000);
+  });
+});

package/tests/core/principle-injector.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from 'vitest';
+import type { PrincipleInjector, InjectionContext } from '../../src/core/principle-injector.js';
+import { DefaultPrincipleInjector } from '../../src/core/principle-injector.js';
+import type { InjectablePrinciple } from '../../src/core/principle-injection.js';
+import { selectPrinciplesForInjection, formatPrinciple } from '../../src/core/principle-injection.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makePrinciple(overrides: Partial<InjectablePrinciple> = {}): InjectablePrinciple {
+  return {
+    id: overrides.id ?? 'P_001',
+    text: overrides.text ?? 'Always verify file content before editing',
+    priority: overrides.priority ?? 'P1',
+    createdAt: overrides.createdAt ?? '2026-04-01T00:00:00.000Z',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('DefaultPrincipleInjector', () => {
+  const injector: PrincipleInjector = new DefaultPrincipleInjector();
+
+  it('getRelevantPrinciples delegates to selectPrinciplesForInjection', () => {
+    const principles = [
+      makePrinciple({ id: 'P0', priority: 'P0', text: 'Critical rule' }),
+      makePrinciple({ id: 'P1', priority: 'P1', text: 'Standard rule' }),
+      makePrinciple({ id: 'P2', priority: 'P2', text: 'Low priority rule' }),
+      makePrinciple({ id: 'P1b', priority: 'P1', text: 'Another standard rule' }),
+      makePrinciple({ id: 'P0b', priority: 'P0', text: 'Another critical rule' }),
+    ];
+    const context: InjectionContext = { domain: 'coding', sessionId: 's-1', budgetChars: 4000 };
+
+    const result = injector.getRelevantPrinciples(principles, context);
+    const expected = selectPrinciplesForInjection(principles, 4000).selected;
+
+    expect(result).toEqual(expected);
+  });
+
+  it('formatForInjection delegates to formatPrinciple', () => {
+    const principle = makePrinciple({ id: 'P_001', text: 'Test' });
+
+    const result = injector.formatForInjection(principle);
+    const expected = formatPrinciple(makePrinciple({ id: 'P_001', text: 'Test' }));
+
+    expect(result).toBe(expected);
+  });
+
+  it('formatForInjection returns "- [ID] text" format', () => {
+    const result = injector.formatForInjection(
+      makePrinciple({ id: 'P_001', text: 'Verify before edit' }),
+    );
+    expect(result).toBe('- [P_001] Verify before edit');
+  });
+
+  it('getRelevantPrinciples respects budget constraint', () => {
+    const principles = Array.from({ length: 20 }, (_, i) =>
+      makePrinciple({
+        id: `P_${i.toString().padStart(3, '0')}`,
+        text: 'A'.repeat(300), // 300 chars each
+        priority: i === 0 ? 'P0' : 'P2',
+      }),
+    );
+    const context: InjectionContext = { domain: 'coding', sessionId: 's-1', budgetChars: 500 };
+
+    const result = injector.getRelevantPrinciples(principles, context);
+
+    // Should include at least the forced P0, total chars may exceed budget slightly
+    expect(result.length).toBeGreaterThan(0);
+    expect(result.some(p => p.priority === 'P0')).toBe(true);
+  });
+
+  it('getRelevantPrinciples returns empty array for empty input', () => {
+    const context: InjectionContext = { domain: 'coding', sessionId: 's-1', budgetChars: 4000 };
+    const result = injector.getRelevantPrinciples([], context);
+    expect(result).toEqual([]);
+  });
+});
+
+describe('InjectionContext', () => {
+  it('has domain, sessionId, and budgetChars fields', () => {
+    const ctx: InjectionContext = { domain: 'coding', sessionId: 's-1', budgetChars: 4000 };
+    expect(ctx.domain).toBe('coding');
+    expect(ctx.sessionId).toBe('s-1');
+    expect(ctx.budgetChars).toBe(4000);
+  });
+});