principles-disciple 1.11.0 → 1.13.0

package/tests/core/principle-internalization/lifecycle-metrics.test.ts

@@ -0,0 +1,350 @@
+import { describe, expect, it } from 'vitest';
+import {
+  computePrincipleAdherence,
+  computeRuleMetrics,
+} from '../../../src/core/principle-internalization/lifecycle-metrics.js';
+import type {
+  PrincipleLifecycleEvidence,
+  RuleLifecycleEvidence,
+} from '../../../src/core/principle-internalization/lifecycle-read-model.js';
+import type { ReplayReport } from '../../../src/core/replay-engine.js';
+import type { ArtifactLineageRecord } from '../../../src/core/nocturnal-artifact-lineage.js';
+
+function createReplayReport(
+  implementationId: string,
+  overrides: Partial<ReplayReport> = {},
+): ReplayReport {
+  return {
+    implementationId,
+    generatedAt: '2026-04-08T00:00:00.000Z',
+    overallDecision: 'pass',
+    blockers: [],
+    sampleFingerprints: [],
+    replayResults: {
+      painNegative: { total: 0, passed: 0, failed: 0, details: [] },
+      successPositive: { total: 0, passed: 0, failed: 0, details: [] },
+      principleAnchor: { total: 0, passed: 0, failed: 0, details: [] },
+    },
+    ...overrides,
+  };
+}
+
+function createLineageRecord(overrides: Partial<ArtifactLineageRecord> = {}): ArtifactLineageRecord {
+  return {
+    artifactKind: 'rule-implementation-candidate',
+    artifactId: 'artifact-1',
+    principleId: 'P-001',
+    ruleId: 'R-001',
+    sessionId: 'session-1',
+    sourceSnapshotRef: 'snapshot-1',
+    sourcePainIds: [],
+    sourceGateBlockIds: [],
+    storagePath: '.state/principles/implementations/IMPL-001',
+    implementationId: 'IMPL-001',
+    createdAt: '2026-04-08T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+function createRuleEvidence(overrides: Partial<RuleLifecycleEvidence> = {}): RuleLifecycleEvidence {
+  return {
+    rule: {
+      id: 'R-001',
+      version: 1,
+      name: 'Protect deletes',
+      description: 'Require safe delete handling',
+      type: 'hook',
+      triggerCondition: 'tool=delete',
+      enforcement: 'block',
+      action: 'block destructive delete',
+      principleId: 'P-001',
+      status: 'enforced',
+      coverageRate: 0,
+      falsePositiveRate: 0,
+      createdAt: '2026-04-08T00:00:00.000Z',
+      updatedAt: '2026-04-08T00:00:00.000Z',
+      implementationIds: ['IMPL-001'],
+    },
+    implementations: [],
+    replayEvidence: {
+      reportCount: 0,
+      latestReports: [],
+      painNegative: { total: 0, passed: 0, failed: 0 },
+      successPositive: { total: 0, passed: 0, failed: 0 },
+      principleAnchor: { total: 0, passed: 0, failed: 0 },
+      passingImplementationIds: [],
+      failingImplementationIds: [],
+      needsReviewImplementationIds: [],
+    },
+    liveEvidence: {
+      activeCount: 0,
+      candidateCount: 0,
+      disabledCount: 0,
+      archivedCount: 0,
+      durablePenaltyCount: 0,
+      rollbackEvidenceCount: 0,
+      hasActiveImplementation: false,
+      hasPassingActiveImplementation: false,
+    },
+    lineageEvidence: {
+      records: [],
+      distinctPainSignalCount: 0,
+      distinctGateBlockCount: 0,
+      repeatedErrorSignal: 0,
+    },
+    ...overrides,
+  };
+}
+
+function createPrincipleEvidence(
+  rules: RuleLifecycleEvidence[],
+  overrides: Partial<PrincipleLifecycleEvidence> = {},
+): PrincipleLifecycleEvidence {
+  return {
+    principle: {
+      id: 'P-001',
+      version: 1,
+      text: 'Write before delete',
+      triggerPattern: 'delete',
+      action: 'write replacement first',
+      status: 'active',
+      priority: 'P1',
+      scope: 'general',
+      evaluability: 'deterministic',
+      valueScore: 0,
+      adherenceRate: 0,
+      painPreventedCount: 0,
+      derivedFromPainIds: [],
+      ruleIds: rules.map((rule) => rule.rule.id),
+      conflictsWithPrincipleIds: [],
+      createdAt: '2026-04-08T00:00:00.000Z',
+      updatedAt: '2026-04-08T00:00:00.000Z',
+    },
+    rules,
+    summary: {
+      replayReportCount: rules.reduce((sum, rule) => sum + rule.replayEvidence.reportCount, 0),
+      activeImplementationCount: rules.reduce((sum, rule) => sum + rule.liveEvidence.activeCount, 0),
+      candidateImplementationCount: rules.reduce((sum, rule) => sum + rule.liveEvidence.candidateCount, 0),
+      disabledImplementationCount: rules.reduce((sum, rule) => sum + rule.liveEvidence.disabledCount, 0),
+      archivedImplementationCount: rules.reduce((sum, rule) => sum + rule.liveEvidence.archivedCount, 0),
+      distinctPainSignalCount: rules.reduce((sum, rule) => sum + rule.lineageEvidence.distinctPainSignalCount, 0),
+      distinctGateBlockCount: rules.reduce((sum, rule) => sum + rule.lineageEvidence.distinctGateBlockCount, 0),
+      repeatedErrorSignal: rules.reduce((sum, rule) => sum + rule.lineageEvidence.repeatedErrorSignal, 0),
+    },
+    ...overrides,
+  };
+}
+
+describe('lifecycle-metrics', () => {
+  it('keeps sparse evidence bounded at zero instead of inferring coverage from implementation existence', () => {
+    const metrics = computeRuleMetrics(createRuleEvidence());
+
+    expect(metrics.coverageRate).toBe(0);
+    expect(metrics.falsePositiveRate).toBe(0);
+    expect(metrics.implementationStabilityScore).toBe(0);
+  });
+
+  it('computes strong rule coverage from replay hits, anchor passes, and stable active implementations', () => {
+    const report = createReplayReport('IMPL-001', {
+      replayResults: {
+        painNegative: { total: 4, passed: 4, failed: 0, details: [] },
+        successPositive: { total: 3, passed: 3, failed: 0, details: [] },
+        principleAnchor: { total: 2, passed: 2, failed: 0, details: [] },
+      },
+    });
+    const metrics = computeRuleMetrics(
+      createRuleEvidence({
+        implementations: [
+          {
+            implementation: {
+              id: 'IMPL-001',
+              ruleId: 'R-001',
+              type: 'code',
+              path: 'impl/entry.js',
+              version: 'v1',
+              coversCondition: 'delete safety',
+              coveragePercentage: 100,
+              lifecycleState: 'active',
+              createdAt: '2026-04-08T00:00:00.000Z',
+              updatedAt: '2026-04-08T00:00:00.000Z',
+            },
+            latestReplayReport: report,
+            replayHistoryCount: 1,
+            lineageRecords: [],
+          },
+        ],
+        replayEvidence: {
+          reportCount: 1,
+          latestReports: [report],
+          painNegative: { total: 4, passed: 4, failed: 0 },
+          successPositive: { total: 3, passed: 3, failed: 0 },
+          principleAnchor: { total: 2, passed: 2, failed: 0 },
+          passingImplementationIds: ['IMPL-001'],
+          failingImplementationIds: [],
+          needsReviewImplementationIds: [],
+        },
+        liveEvidence: {
+          activeCount: 1,
+          candidateCount: 0,
+          disabledCount: 0,
+          archivedCount: 0,
+          durablePenaltyCount: 0,
+          rollbackEvidenceCount: 0,
+          hasActiveImplementation: true,
+          hasPassingActiveImplementation: true,
+        },
+      }),
+    );
+
+    expect(metrics.coverageRate).toBe(98);
+    expect(metrics.falsePositiveRate).toBe(0);
+    expect(metrics.implementationStabilityScore).toBe(90);
+  });
+
+  it('grounds false-positive rate in success-positive replay failures and only adds a coarse live penalty', () => {
+    const report = createReplayReport('IMPL-001', {
+      overallDecision: 'needs-review',
+      replayResults: {
+        painNegative: { total: 2, passed: 2, failed: 0, details: [] },
+        successPositive: { total: 4, passed: 1, failed: 3, details: [] },
+        principleAnchor: { total: 2, passed: 2, failed: 0, details: [] },
+      },
+    });
+    const metrics = computeRuleMetrics(
+      createRuleEvidence({
+        replayEvidence: {
+          reportCount: 1,
+          latestReports: [report],
+          painNegative: { total: 2, passed: 2, failed: 0 },
+          successPositive: { total: 4, passed: 1, failed: 3 },
+          principleAnchor: { total: 2, passed: 2, failed: 0 },
+          passingImplementationIds: [],
+          failingImplementationIds: [],
+          needsReviewImplementationIds: ['IMPL-001'],
+        },
+        liveEvidence: {
+          activeCount: 1,
+          candidateCount: 0,
+          disabledCount: 1,
+          archivedCount: 0,
+          durablePenaltyCount: 1,
+          rollbackEvidenceCount: 0,
+          hasActiveImplementation: true,
+          hasPassingActiveImplementation: false,
+        },
+      }),
+    );
+
+    expect(metrics.replayFalsePositiveRate).toBe(75);
+    expect(metrics.livePenaltyRate).toBe(5);
+    expect(metrics.falsePositiveRate).toBe(80);
+  });
+
+  it('penalizes rollback and repeated errors when computing principle adherence', () => {
+    const stableRule = createRuleEvidence({
+      rule: {
+        ...createRuleEvidence().rule,
+        id: 'R-001',
+      },
+      replayEvidence: {
+        reportCount: 1,
+        latestReports: [createReplayReport('IMPL-001')],
+        painNegative: { total: 3, passed: 3, failed: 0 },
+        successPositive: { total: 2, passed: 2, failed: 0 },
+        principleAnchor: { total: 2, passed: 2, failed: 0 },
+        passingImplementationIds: ['IMPL-001'],
+        failingImplementationIds: [],
+        needsReviewImplementationIds: [],
+      },
+      liveEvidence: {
+        activeCount: 1,
+        candidateCount: 0,
+        disabledCount: 0,
+        archivedCount: 0,
+        durablePenaltyCount: 0,
+        rollbackEvidenceCount: 0,
+        hasActiveImplementation: true,
+        hasPassingActiveImplementation: true,
+      },
+    });
+    const unstableRule = createRuleEvidence({
+      rule: {
+        ...createRuleEvidence().rule,
+        id: 'R-002',
+        implementationIds: ['IMPL-002'],
+      },
+      implementations: [
+        {
+          implementation: {
+            id: 'IMPL-002',
+            ruleId: 'R-002',
+            type: 'code',
+            path: 'impl/rollback.js',
+            version: 'v2',
+            coversCondition: 'delete safety',
+            coveragePercentage: 70,
+            lifecycleState: 'disabled',
+            previousActive: 'IMPL-001',
+            disabledReason: 'Rollback after false positive spike',
+            createdAt: '2026-04-08T00:00:00.000Z',
+            updatedAt: '2026-04-08T00:00:00.000Z',
+          },
+          latestReplayReport: createReplayReport('IMPL-002', {
+            overallDecision: 'needs-review',
+            replayResults: {
+              painNegative: { total: 2, passed: 1, failed: 1, details: [] },
+              successPositive: { total: 2, passed: 1, failed: 1, details: [] },
+              principleAnchor: { total: 2, passed: 1, failed: 1, details: [] },
+            },
+          }),
+          replayHistoryCount: 1,
+          lineageRecords: [createLineageRecord({ sourcePainIds: ['pain-1', 'pain-2'] })],
+        },
+      ],
+      replayEvidence: {
+        reportCount: 1,
+        latestReports: [
+          createReplayReport('IMPL-002', {
+            overallDecision: 'needs-review',
+            replayResults: {
+              painNegative: { total: 2, passed: 1, failed: 1, details: [] },
+              successPositive: { total: 2, passed: 1, failed: 1, details: [] },
+              principleAnchor: { total: 2, passed: 1, failed: 1, details: [] },
+            },
+          }),
+        ],
+        painNegative: { total: 2, passed: 1, failed: 1 },
+        successPositive: { total: 2, passed: 1, failed: 1 },
+        principleAnchor: { total: 2, passed: 1, failed: 1 },
+        passingImplementationIds: [],
+        failingImplementationIds: [],
+        needsReviewImplementationIds: ['IMPL-002'],
+      },
+      liveEvidence: {
+        activeCount: 0,
+        candidateCount: 0,
+        disabledCount: 1,
+        archivedCount: 0,
+        durablePenaltyCount: 1,
+        rollbackEvidenceCount: 1,
+        hasActiveImplementation: false,
+        hasPassingActiveImplementation: false,
+      },
+      lineageEvidence: {
+        records: [createLineageRecord({ ruleId: 'R-002', implementationId: 'IMPL-002', sourcePainIds: ['pain-1', 'pain-2'] })],
+        distinctPainSignalCount: 2,
+        distinctGateBlockCount: 0,
+        repeatedErrorSignal: 2,
+        latestCreatedAt: '2026-04-08T00:00:00.000Z',
+      },
+    });
+
+    const adherence = computePrincipleAdherence(createPrincipleEvidence([stableRule, unstableRule]));
+
+    expect(adherence.averageRuleCoverage).toBe(69);
+    expect(adherence.repeatedErrorReductionScore).toBe(56.4);
+    expect(adherence.adherenceRate).toBe(65.22);
+    expect(adherence.stableRuleIds).toEqual(['R-001']);
+    expect(adherence.unstableRuleIds).toEqual(['R-002']);
+  });
+});

package/tests/core/principle-internalization/principle-lifecycle-service.test.ts

@@ -0,0 +1,211 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { PrincipleLifecycleService } from '../../../src/core/principle-internalization/principle-lifecycle-service.js';
+import { appendCandidateArtifactLineageRecord, listArtifactLineageRecords } from '../../../src/core/nocturnal-artifact-lineage.js';
+import { getImplementationAssetRoot } from '../../../src/core/code-implementation-storage.js';
+import { loadLedger, saveLedger, type LedgerPrinciple, type LedgerRule } from '../../../src/core/principle-tree-ledger.js';
+import type { Implementation } from '../../../src/types/principle-tree-schema.js';
+import type { ReplayReport } from '../../../src/core/replay-engine.js';
+import { createTestContext, safeRmDir } from '../../test-utils.js';
+
+function makePrinciple(overrides: Partial<LedgerPrinciple> = {}): LedgerPrinciple {
+  return {
+    id: 'P-001',
+    version: 1,
+    text: 'Prefer cheap safe internalization',
+    triggerPattern: 'write',
+    action: 'prefer the cheapest viable fix',
+    status: 'active',
+    priority: 'P1',
+    scope: 'general',
+    evaluability: 'weak_heuristic',
+    valueScore: 0,
+    adherenceRate: 0,
+    painPreventedCount: 0,
+    derivedFromPainIds: [],
+    ruleIds: ['R-001'],
+    conflictsWithPrincipleIds: [],
+    createdAt: '2026-04-08T00:00:00.000Z',
+    updatedAt: '2026-04-08T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+function makeRule(overrides: Partial<LedgerRule> = {}): LedgerRule {
+  return {
+    id: 'R-001',
+    version: 1,
+    name: 'Coach cautious writes',
+    description: 'Encourage safer writes before escalating to hard boundaries.',
+    type: 'skill',
+    triggerCondition: 'tool=write',
+    enforcement: 'warn',
+    action: 'warn before risky write',
+    principleId: 'P-001',
+    status: 'implemented',
+    coverageRate: 0,
+    falsePositiveRate: 0,
+    implementationIds: ['IMPL-001'],
+    createdAt: '2026-04-08T00:00:00.000Z',
+    updatedAt: '2026-04-08T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+function makeImplementation(overrides: Partial<Implementation> = {}): Implementation {
+  return {
+    id: 'IMPL-001',
+    ruleId: 'R-001',
+    type: 'code',
+    path: 'implementations/IMPL-001/entry.js',
+    version: 'v1',
+    coversCondition: 'risky write',
+    coveragePercentage: 60,
+    lifecycleState: 'candidate',
+    createdAt: '2026-04-08T00:00:00.000Z',
+    updatedAt: '2026-04-08T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+function makeReplayReport(overrides: Partial<ReplayReport> = {}): ReplayReport {
+  return {
+    implementationId: 'IMPL-001',
+    generatedAt: '2026-04-08T00:00:00.000Z',
+    overallDecision: 'needs-review',
+    blockers: [],
+    sampleFingerprints: ['sample-1', 'sample-2', 'sample-3'],
+    replayResults: {
+      painNegative: { total: 2, passed: 2, failed: 0, details: [] },
+      successPositive: { total: 2, passed: 1, failed: 1, details: [] },
+      principleAnchor: { total: 1, passed: 1, failed: 0, details: [] },
+    },
+    ...overrides,
+  };
+}
+
+describe('principle-lifecycle-service', () => {
+  let tempDir: string;
+  let workspaceDir: string;
+  let stateDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-lifecycle-service-'));
+    workspaceDir = path.join(tempDir, 'workspace');
+    stateDir = path.join(tempDir, 'state');
+    fs.mkdirSync(workspaceDir, { recursive: true });
+    fs.mkdirSync(stateDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    safeRmDir(tempDir);
+  });
+
+  function seedWorkspace(): void {
+    saveLedger(stateDir, {
+      trainingStore: {
+        'P-001': {
+          principleId: 'P-001',
+          evaluability: 'weak_heuristic',
+          applicableOpportunityCount: 5,
+          observedViolationCount: 2,
+          complianceRate: 0.6,
+          violationTrend: -0.2,
+          generatedSampleCount: 0,
+          approvedSampleCount: 0,
+          includedTrainRunIds: [],
+          deployedCheckpointIds: [],
+          internalizationStatus: 'internalized',
+        },
+      },
+      tree: {
+        principles: {
+          'P-001': makePrinciple(),
+        },
+        rules: {
+          'R-001': makeRule(),
+        },
+        implementations: {
+          'IMPL-001': makeImplementation(),
+        },
+        metrics: {},
+        lastUpdated: '2026-04-08T00:00:00.000Z',
+      },
+    });
+
+    const replayDir = path.join(getImplementationAssetRoot(stateDir, 'IMPL-001'), 'replays');
+    fs.mkdirSync(replayDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(replayDir, '2026-04-08T00-00-00-000Z.json'),
+      JSON.stringify(makeReplayReport(), null, 2),
+      'utf-8',
+    );
+
+    appendCandidateArtifactLineageRecord(workspaceDir, {
+      artifactId: 'artifact-1',
+      principleId: 'P-001',
+      ruleId: 'R-001',
+      sessionId: 'session-1',
+      sourceSnapshotRef: 'snapshot-1',
+      sourcePainIds: ['pain-1'],
+      sourceGateBlockIds: ['gate-1'],
+      storagePath: getImplementationAssetRoot(stateDir, 'IMPL-001'),
+      implementationId: 'IMPL-001',
+      createdAt: '2026-04-08T00:00:00.000Z',
+    });
+  }
+
+  it('recomputes lifecycle metrics and exposes assessments plus route recommendations through one service', () => {
+    seedWorkspace();
+    const service = new PrincipleLifecycleService(workspaceDir, stateDir);
+
+    const recomputed = service.recomputeAll();
+    const assessments = service.listAssessments();
+    const recommendations = service.listRouteRecommendations();
+    const ledger = loadLedger(stateDir);
+
+    expect(recomputed).toHaveLength(1);
+    expect(recomputed[0].routeRecommendation.route).toBe('skill');
+    expect(assessments).toHaveLength(1);
+    expect(assessments[0].deprecatedReadiness.status).toBe('not-ready');
+    expect(recommendations).toEqual([assessments[0].routeRecommendation]);
+    expect(ledger.tree.rules['R-001'].coverageRate).toBeGreaterThan(0);
+    expect(ledger.tree.principles['P-001'].adherenceRate).toBeGreaterThan(0);
+    expect(ledger.tree.metrics['P-001']).toBeDefined();
+  });
+
+  it('surfaces the lifecycle service from WorkspaceContext without breaking existing consumers', () => {
+    seedWorkspace();
+    const context = createTestContext({ workspaceDir, stateDir });
+
+    expect(context.principleLifecycle).toBeInstanceOf(PrincipleLifecycleService);
+    expect(context.principleLifecycle.listAssessments()).toHaveLength(1);
+    expect(context.getActivePrincipleSubtrees()).toEqual([]);
+  });
+
+  it('keeps replay classifications behavioral-only and preserves candidate lineage semantics', () => {
+    seedWorkspace();
+    const service = new PrincipleLifecycleService(workspaceDir, stateDir);
+
+    const assessments = service.listAssessments();
+    const readModel = service.buildReadModel();
+    const lineage = listArtifactLineageRecords(workspaceDir, 'rule-implementation-candidate');
+    const latestReport = readModel.principles[0].rules[0].replayEvidence.latestReports[0];
+
+    expect(assessments[0].routeRecommendation.route).toBe('skill');
+    expect(Object.keys(latestReport.replayResults)).toEqual([
+      'painNegative',
+      'successPositive',
+      'principleAnchor',
+    ]);
+    expect(lineage).toHaveLength(1);
+    expect(lineage[0]).toMatchObject({
+      artifactKind: 'rule-implementation-candidate',
+      sourcePainIds: ['pain-1'],
+      sourceGateBlockIds: ['gate-1'],
+      implementationId: 'IMPL-001',
+    });
+  });
+});