principles-disciple 1.11.0 → 1.13.0

package/src/core/pd-task-types.ts

@@ -0,0 +1,128 @@
+/**
+ * PD Task Manager Types
+ *
+ * Type definitions for the PD Task Manager — a declarative cron task
+ * management system that reconciles PD task declarations with OpenClaw's
+ * cron/jobs.json using safe file operations (lock + atomic write).
+ */
+
+// =========================================================================
+// PDTaskSpec — Declaration Schema
+// =========================================================================
+
+/** Cron schedule for PD tasks (only "every" kind supported for now) */
+export interface PDTaskSchedule {
+  kind: 'every';
+  everyMs: number;
+}
+
+/** Execution configuration for a PD task */
+export interface PDTaskExecution {
+  /** Which prompt builder to use */
+  promptTemplate: string;
+  /** Execution timeout in seconds (default: 120) */
+  timeoutSeconds?: number;
+  /** Use lightweight context to save tokens */
+  lightContext?: boolean;
+  /** Restrict available tools */
+  toolsAllow?: string[];
+}
+
+/** Delivery configuration for task results */
+export interface PDTaskDelivery {
+  mode: 'none' | 'announce';
+  channel?: string;
+  to?: string;
+}
+
+/** Metadata — not synced to cron, used for health tracking */
+export interface PDTaskMeta {
+  /** When this task was first declared */
+  createdAtMs?: number;
+  /** Last successful reconcile timestamp */
+  lastSyncedAtMs?: number;
+  /** The cron job ID from last sync */
+  lastSyncedJobId?: string;
+  /** Last sync status */
+  lastSyncStatus?: 'ok' | 'error';
+  /** Last sync error message */
+  lastSyncError?: string;
+  /** Consecutive failure count (from CronJobState.consecutiveErrors) */
+  consecutiveFailCount?: number;
+  /** Timestamp of last failure */
+  lastFailedAtMs?: number;
+  /** Whether this task was auto-disabled due to health issues */
+  autoDisabled?: boolean;
+  /** When the task was auto-disabled */
+  autoDisabledAt?: number;
+  /** Reason for auto-disable */
+  autoDisabledReason?: string;
+  /** Last manual trigger timestamp */
+  lastTriggeredAtMs?: number;
+  /** Last manual trigger status */
+  lastTriggerStatus?: 'succeeded' | 'failed' | 'pending';
+}
+
+/**
+ * PDTaskSpec — A declarative specification for a PD background task.
+ *
+ * This is the source of truth. The reconciler translates these into
+ * CronJob entries in OpenClaw's cron/jobs.json.
+ */
+export interface PDTaskSpec {
+  /** Stable unique ID — never changes across versions */
+  id: string;
+  /** Human-readable name — becomes the CronJob name (must start with "PD ") */
+  name: string;
+  /** Description shown to users */
+  description: string;
+  /** Whether this task should be active */
+  enabled: boolean;
+  /** Schema version — bumped when prompt/config changes require re-sync */
+  version: string;
+  /** Cron schedule (only "every" kind supported for now) */
+  schedule: PDTaskSchedule;
+  /** OpenClaw agent ID to run under (default: "main") */
+  agentId?: string;
+  /** Execution configuration */
+  execution: PDTaskExecution;
+  /** Delivery configuration */
+  delivery: PDTaskDelivery;
+  /** Metadata — not synced to cron */
+  meta?: PDTaskMeta;
+}
+
+// =========================================================================
+// Builtin PD Tasks
+// =========================================================================
+
+/**
+ * Built-in PD tasks declared by the plugin.
+ *
+ * These are reconciled on plugin startup. Adding a new task here
+ * automatically creates the corresponding cron job on next restart.
+ */
+export const BUILTIN_PD_TASKS: PDTaskSpec[] = [
+  {
+    id: 'empathy-optimizer',
+    name: 'PD Empathy Optimizer',
+    description:
+      'Analyzes recent user messages to discover new frustration expressions and optimize keyword weights.',
+    enabled: true,
+    version: '1.0.1', // Bumped to force cron job settings update
+    schedule: {
+      kind: 'every',
+      everyMs: 5 * 60 * 1000, // 5 minutes (testing); increase to 6h once stable
+    },
+    agentId: 'main',
+    execution: {
+      promptTemplate: 'empathy-optimizer',
+      timeoutSeconds: 300, // 5 min — needs time to scan events.jsonl
+      lightContext: true,
+      toolsAllow: ['read_file', 'write_file', 'search_file_content'],
+    },
+    delivery: {
+      mode: 'none',
+    },
+  },
+];

package/src/core/principle-internalization/deprecated-readiness.ts

@@ -0,0 +1,91 @@
+import type { PrincipleLifecycleEvidence } from './lifecycle-read-model.js';
+import { computePrincipleAdherence, computeRuleMetrics, type PrincipleAdherenceResult, type RuleMetricResult } from './lifecycle-metrics.js';
+
+export type DeprecatedReadinessStatus = 'ready' | 'watch' | 'not-ready';
+
+export interface DeprecatedReadinessAssessment {
+  status: DeprecatedReadinessStatus;
+  score: number;
+  blockingReasons: string[];
+  supportingRuleIds: string[];
+  evidence: {
+    adherenceRate: number;
+    averageRuleCoverage: number;
+    averageFalsePositiveRate: number;
+    repeatedErrorReductionScore: number;
+    repeatedErrorSignal: number;
+    stableRuleCount: number;
+    activeImplementationCount: number;
+  };
+}
+
+function clampScore(value: number): number {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+
+  return Math.max(0, Math.min(100, Number(value.toFixed(2))));
+}
+
+export function assessDeprecatedReadiness(
+  principle: PrincipleLifecycleEvidence,
+  precomputedRuleMetrics?: Record<string, RuleMetricResult>,
+  precomputedAdherence?: PrincipleAdherenceResult,
+): DeprecatedReadinessAssessment {
+  const ruleMetrics = precomputedRuleMetrics ?? Object.fromEntries(
+    principle.rules.map((rule) => [rule.rule.id, computeRuleMetrics(rule)]),
+  );
+  const adherence = precomputedAdherence ?? computePrincipleAdherence(principle, ruleMetrics);
+  const blockingReasons: string[] = [];
+  const stableCoverageRatio =
+    principle.rules.length > 0 ? adherence.stableRuleIds.length / principle.rules.length : 0;
+
+  if (principle.rules.length === 0) {
+    blockingReasons.push('No material rules are attached to this principle yet.');
+  }
+  if (principle.summary.activeImplementationCount === 0) {
+    blockingReasons.push('No active lower-layer implementation is absorbing the principle.');
+  }
+  if (adherence.averageRuleCoverage < 75) {
+    blockingReasons.push('Rule coverage is not yet stable enough to absorb the principle.');
+  }
+  if (adherence.averageFalsePositiveRate > 20) {
+    blockingReasons.push('False-positive rate remains too high for deprecation readiness.');
+  }
+  if (adherence.repeatedErrorSignal > 0 || adherence.repeatedErrorReductionScore < 70) {
+    blockingReasons.push('Repeated related errors have not fallen enough yet.');
+  }
+
+  const score = clampScore(
+    adherence.adherenceRate * 0.45 +
+      adherence.averageRuleCoverage * 0.25 +
+      (100 - adherence.averageFalsePositiveRate) * 0.15 +
+      adherence.repeatedErrorReductionScore * 0.15,
+  );
+
+  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in all if/else branches
+  let status: DeprecatedReadinessStatus;
+  if (blockingReasons.length === 0 && stableCoverageRatio === 1) {
+    status = 'ready';
+  } else if (score >= 55 && principle.summary.activeImplementationCount > 0 && stableCoverageRatio >= 0.5) {
+    status = 'watch';
+  } else {
+    status = 'not-ready';
+  }
+
+  return {
+    status,
+    score,
+    blockingReasons,
+    supportingRuleIds: adherence.stableRuleIds,
+    evidence: {
+      adherenceRate: adherence.adherenceRate,
+      averageRuleCoverage: adherence.averageRuleCoverage,
+      averageFalsePositiveRate: adherence.averageFalsePositiveRate,
+      repeatedErrorReductionScore: adherence.repeatedErrorReductionScore,
+      repeatedErrorSignal: adherence.repeatedErrorSignal,
+      stableRuleCount: adherence.stableRuleIds.length,
+      activeImplementationCount: principle.summary.activeImplementationCount,
+    },
+  };
+}

package/src/core/principle-internalization/internalization-routing-policy.ts

@@ -0,0 +1,208 @@
+import type { PrinciplePriority, PrincipleEvaluability, RuleType } from '../../types/principle-tree-schema.js';
+import type { PrincipleLifecycleEvidence } from './lifecycle-read-model.js';
+import {
+  computePrincipleAdherence,
+  computeRuleMetrics,
+  type PrincipleAdherenceResult,
+  type RuleMetricResult,
+} from './lifecycle-metrics.js';
+
+export type InternalizationRoute = 'skill' | 'code' | 'defer';
+
+export interface InternalizationRouteEvidenceSummary {
+  replayReportCount: number;
+  activeImplementationCount: number;
+  candidateImplementationCount: number;
+  repeatedErrorSignal: number;
+  averageRuleCoverage: number;
+  averageFalsePositiveRate: number;
+  highestRuleCoverageGap: number;
+  dominantRuleType: RuleType | 'mixed';
+}
+
+export interface InternalizationRouteRecommendation {
+  principleId: string;
+  route: InternalizationRoute;
+  confidence: number;
+  reasonCodes: string[];
+  evidenceSummary: InternalizationRouteEvidenceSummary;
+  nextAction: string;
+}
+
+function clampToPercentage(value: number): number {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+
+  return Math.max(0, Math.min(100, Number(value.toFixed(2))));
+}
+
+function dominantRuleType(principle: PrincipleLifecycleEvidence): RuleType | 'mixed' {
+  if (principle.rules.length === 0) {
+    return 'mixed';
+  }
+
+  const distinctTypes = Array.from(new Set(principle.rules.map((rule) => rule.rule.type)));
+  return distinctTypes.length === 1 ? distinctTypes[0] : 'mixed';
+}
+
+function averageCoverageGap(ruleMetrics: Record<string, RuleMetricResult>): number {
+  const coverageGaps = Object.values(ruleMetrics).map((metrics) => Math.max(0, 100 - metrics.coverageRate));
+
+  if (coverageGaps.length === 0) {
+    return 0;
+  }
+
+  return clampToPercentage(
+    coverageGaps.reduce((sum, gap) => sum + gap, 0) / coverageGaps.length,
+  );
+}
+
+function isHighRisk(priority: PrinciplePriority, evaluability: PrincipleEvaluability): boolean {
+  return priority === 'P0' || evaluability === 'deterministic';
+}
+
+function supportsSkillRoute(principle: PrincipleLifecycleEvidence): boolean {
+  return principle.rules.every((rule) =>
+    rule.rule.enforcement !== 'block' || ['skill', 'prompt', 'test'].includes(rule.rule.type),
+  );
+}
+
+function buildEvidenceSummary(
+  principle: PrincipleLifecycleEvidence,
+  adherence: PrincipleAdherenceResult,
+  ruleMetrics: Record<string, RuleMetricResult>,
+): InternalizationRouteEvidenceSummary {
+  return {
+    replayReportCount: principle.summary.replayReportCount,
+    activeImplementationCount: principle.summary.activeImplementationCount,
+    candidateImplementationCount: principle.summary.candidateImplementationCount,
+    repeatedErrorSignal: principle.summary.repeatedErrorSignal,
+    averageRuleCoverage: adherence.averageRuleCoverage,
+    averageFalsePositiveRate: adherence.averageFalsePositiveRate,
+    highestRuleCoverageGap: averageCoverageGap(ruleMetrics),
+    dominantRuleType: dominantRuleType(principle),
+  };
+}
+
+export function recommendInternalizationRoute(
+  principle: PrincipleLifecycleEvidence,
+  precomputedRuleMetrics?: Record<string, RuleMetricResult>,
+  precomputedAdherence?: PrincipleAdherenceResult,
+): InternalizationRouteRecommendation {
+  const ruleMetrics = precomputedRuleMetrics ?? Object.fromEntries(
+    principle.rules.map((rule) => [rule.rule.id, computeRuleMetrics(rule)]),
+  );
+  const adherence = precomputedAdherence ?? computePrincipleAdherence(principle, ruleMetrics);
+  const evidenceSummary = buildEvidenceSummary(principle, adherence, ruleMetrics);
+    const reasonCodes: string[] = [];
+  
+  // ── Axiom-based heuristic modifiers ──
+  const axiomId = principle.principle.coreAxiomId;
+  let codeBoost = 0;
+  let skillBoost = 0;
+  if (axiomId === 'T-05' || axiomId === 'T-08') {
+    codeBoost = 15;
+    reasonCodes.push('axiom_governance_enforcement');
+  } else if (axiomId === 'T-01' || axiomId === 'T-03' || axiomId === 'T-04') {
+    skillBoost = 15;
+    reasonCodes.push('axiom_knowledge_guidance');
+  }
+
+  const highRisk = isHighRisk(principle.principle.priority, principle.principle.evaluability);
+  const hasSparseEvidence =
+    principle.summary.replayReportCount < Math.max(1, principle.rules.length) &&
+    principle.summary.activeImplementationCount === 0 &&
+    principle.summary.candidateImplementationCount === 0 &&
+    principle.summary.repeatedErrorSignal < 2;
+  const stableEnoughToWait =
+    adherence.averageRuleCoverage >= 80 &&
+    adherence.averageFalsePositiveRate <= 15 &&
+    principle.summary.repeatedErrorSignal === 0;
+
+  if (principle.rules.length === 0) {
+    reasonCodes.push('no_material_rules');
+    return {
+      principleId: principle.principle.id,
+      route: 'defer',
+      confidence: 95,
+      reasonCodes,
+      evidenceSummary,
+      nextAction: 'Define at least one concrete rule before choosing an internalization route.',
+    };
+  }
+
+  if (hasSparseEvidence) {
+    reasonCodes.push('sparse_evidence');
+    return {
+      principleId: principle.principle.id,
+      route: 'defer',
+      confidence: clampToPercentage(78 - principle.summary.repeatedErrorSignal * 8),
+      reasonCodes,
+      evidenceSummary,
+      nextAction: 'Collect more replay evidence or live violations before committing to a heavier implementation path.',
+    };
+  }
+
+  if (stableEnoughToWait) {
+    reasonCodes.push('already_absorbing');
+    return {
+      principleId: principle.principle.id,
+      route: 'defer',
+      confidence: clampToPercentage(70 + adherence.averageRuleCoverage * 0.2),
+      reasonCodes,
+      evidenceSummary,
+      nextAction: 'Defer new implementation work and keep monitoring until the lower layer proves it needs another route.',
+    };
+  }
+
+  const prefersSkillRoute =
+    supportsSkillRoute(principle) &&
+    (
+      (!highRisk &&
+      principle.principle.evaluability !== 'deterministic' &&
+      principle.summary.repeatedErrorSignal <= 2) ||
+      (skillBoost > 0 && codeBoost === 0)
+    ) && codeBoost === 0;
+
+  if (prefersSkillRoute) {
+    reasonCodes.push('cheapest_viable_skill');
+    if (principle.summary.activeImplementationCount === 0) {
+      reasonCodes.push('no_hard_boundary_required');
+    }
+
+    return {
+      principleId: principle.principle.id,
+      route: 'skill',
+      confidence: clampToPercentage(
+        62 + adherence.repeatedErrorReductionScore * 0.12 - adherence.averageFalsePositiveRate * 0.15 + skillBoost,
+      ),
+      reasonCodes,
+      evidenceSummary,
+      nextAction: 'Prefer a skill or prompt-level intervention first, then replay again before escalating to code.',
+    };
+  }
+
+  reasonCodes.push('deterministic_or_high_risk');
+  if (principle.summary.replayReportCount > 0) {
+    reasonCodes.push('replay_evidence_sufficient');
+  }
+  if (principle.summary.repeatedErrorSignal > 0) {
+    reasonCodes.push('repeated_errors_continue');
+  }
+
+  return {
+    principleId: principle.principle.id,
+    route: 'code',
+    confidence: clampToPercentage(
+      58 +
+        evidenceSummary.highestRuleCoverageGap * 0.2 +
+        principle.summary.repeatedErrorSignal * 6 +
+        (highRisk ? 8 : 0) +
+        codeBoost,
+    ),
+    reasonCodes,
+    evidenceSummary,
+    nextAction: 'Prepare a code implementation candidate and keep promotion manual after replay validation.',
+  };
+}

package/src/core/principle-internalization/lifecycle-metrics.ts

@@ -0,0 +1,149 @@
+import type { PrincipleLifecycleEvidence, RuleLifecycleEvidence } from './lifecycle-read-model.js';
+
+export interface RuleMetricResult {
+  coverageRate: number;
+  falsePositiveRate: number;
+  painNegativeHitRate: number;
+  principleAnchorPassRate: number;
+  implementationStabilityScore: number;
+  replayFalsePositiveRate: number;
+  livePenaltyRate: number;
+}
+
+export interface PrincipleAdherenceResult {
+  adherenceRate: number;
+  averageRuleCoverage: number;
+  averageFalsePositiveRate: number;
+  repeatedErrorReductionScore: number;
+  repeatedErrorSignal: number;
+  stableRuleIds: string[];
+  unstableRuleIds: string[];
+}
+
+function clampRate(value: number): number {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+
+  return Math.max(0, Math.min(100, Number(value.toFixed(2))));
+}
+
+function ratio(passed: number, total: number): number {
+  if (total <= 0) {
+    return 0;
+  }
+
+  return (passed / total) * 100;
+}
+
+function computeImplementationStabilityScore(rule: RuleLifecycleEvidence): number {
+  const { liveEvidence, replayEvidence } = rule;
+
+  let score = 0;
+
+  if (liveEvidence.hasActiveImplementation) {
+    score += 35;
+  }
+  if (liveEvidence.hasPassingActiveImplementation) {
+    score += 30;
+  } else if (replayEvidence.passingImplementationIds.length > 0) {
+    score += 20;
+  }
+  if (liveEvidence.candidateCount > 0) {
+    score += 10;
+  }
+  if (replayEvidence.reportCount > 0) {
+    score += 15;
+  }
+  if (
+    liveEvidence.hasActiveImplementation &&
+    liveEvidence.durablePenaltyCount === 0 &&
+    liveEvidence.rollbackEvidenceCount === 0
+  ) {
+    score += 10;
+  }
+
+  score -= liveEvidence.durablePenaltyCount * 12;
+  score -= liveEvidence.rollbackEvidenceCount * 8;
+
+  return clampRate(score);
+}
+
+export function computeRuleMetrics(rule: RuleLifecycleEvidence): RuleMetricResult {
+  const painNegativeHitRate = ratio(rule.replayEvidence.painNegative.passed, rule.replayEvidence.painNegative.total);
+  const principleAnchorPassRate = ratio(
+    rule.replayEvidence.principleAnchor.passed,
+    rule.replayEvidence.principleAnchor.total,
+  );
+  const implementationStabilityScore = computeImplementationStabilityScore(rule);
+  const replayFalsePositiveRate = ratio(
+    rule.replayEvidence.successPositive.failed,
+    rule.replayEvidence.successPositive.total,
+  );
+  const livePenaltyRate = Math.min(
+    15,
+    rule.liveEvidence.durablePenaltyCount * 5 + rule.liveEvidence.rollbackEvidenceCount * 3,
+  );
+
+  return {
+    coverageRate: clampRate(
+      painNegativeHitRate * 0.5 + principleAnchorPassRate * 0.3 + implementationStabilityScore * 0.2,
+    ),
+    falsePositiveRate: clampRate(replayFalsePositiveRate + livePenaltyRate),
+    painNegativeHitRate: clampRate(painNegativeHitRate),
+    principleAnchorPassRate: clampRate(principleAnchorPassRate),
+    implementationStabilityScore,
+    replayFalsePositiveRate: clampRate(replayFalsePositiveRate),
+    livePenaltyRate: clampRate(livePenaltyRate),
+  };
+}
+
+export function computePrincipleAdherence(
+  principle: PrincipleLifecycleEvidence,
+  precomputedRuleMetrics?: Record<string, RuleMetricResult>,
+): PrincipleAdherenceResult {
+  const metricsByRuleId = precomputedRuleMetrics ?? Object.fromEntries(
+    principle.rules.map((rule) => [rule.rule.id, computeRuleMetrics(rule)]),
+  );
+
+  if (principle.rules.length === 0) {
+    return {
+      adherenceRate: 0,
+      averageRuleCoverage: 0,
+      averageFalsePositiveRate: 0,
+      repeatedErrorReductionScore: 0,
+      repeatedErrorSignal: principle.summary.repeatedErrorSignal,
+      stableRuleIds: [],
+      unstableRuleIds: [],
+    };
+  }
+
+  const ruleMetrics = principle.rules.map((rule) => ({
+    ruleId: rule.rule.id,
+    metrics: metricsByRuleId[rule.rule.id] ?? computeRuleMetrics(rule),
+  }));
+  const averageRuleCoverage = ruleMetrics.reduce((sum, entry) => sum + entry.metrics.coverageRate, 0) / ruleMetrics.length;
+  const averageFalsePositiveRate =
+    ruleMetrics.reduce((sum, entry) => sum + entry.metrics.falsePositiveRate, 0) / ruleMetrics.length;
+
+  const stableRuleIds = ruleMetrics
+    .filter((entry) => entry.metrics.coverageRate >= 70 && entry.metrics.falsePositiveRate <= 25)
+    .map((entry) => entry.ruleId);
+  const unstableRuleIds = ruleMetrics
+    .filter((entry) => !stableRuleIds.includes(entry.ruleId))
+    .map((entry) => entry.ruleId);
+
+  const repeatedErrorPressure =
+    principle.summary.repeatedErrorSignal * 10 + unstableRuleIds.length * 12 + averageFalsePositiveRate * 0.4;
+  const repeatedErrorReductionScore = clampRate(100 - repeatedErrorPressure);
+
+  return {
+    adherenceRate: clampRate(averageRuleCoverage * 0.7 + repeatedErrorReductionScore * 0.3),
+    averageRuleCoverage: clampRate(averageRuleCoverage),
+    averageFalsePositiveRate: clampRate(averageFalsePositiveRate),
+    repeatedErrorReductionScore,
+    repeatedErrorSignal: principle.summary.repeatedErrorSignal,
+    stableRuleIds,
+    unstableRuleIds,
+  };
+}