principles-disciple 1.7.5 → 1.7.8

package/dist/service/nocturnal-target-selector.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Nocturnal Target Selector — Principle + Session Selection for Sleep-Mode Reflection
+ * ================================================================================
+ *
+ * PURPOSE: Select one target principle and one violating session for nocturnal
+ * reflection processing. This module is a PURE SELECTOR — it does NOT execute
+ * reflection or write any artifacts.
+ *
+ * SELECTION LOGIC:
+ * 1. Filter principles to evaluable candidates (not manual_only, not cooldown)
+ * 2. Score candidates by: compliance health, violation trend, sample scarcity
+ * 3. Select top principle
+ * 4. Find violating sessions for that principle
+ * 5. Select best violating session by violation density
+ *
+ * SKIP CONDITIONS (return no-op cleanly):
+ * - no_evaluable_principles: No principles with auto-trainable evaluability
+ * - all_targets_in_cooldown: All candidates are in cooldown
+ * - no_violating_sessions: No sessions show violation signals for selected principle
+ * - workspace_not_idle: Workspace is active, nocturnal run not allowed
+ * - quota_exhausted: Max runs per window reached
+ * - insufficient_snapshot_data: Sessions exist but lack tool calls
+ *
+ * DESIGN CONSTRAINTS:
+ * - This is a PURE SELECTOR — no reflection execution
+ * - No raw text exposure
+ * - No artifact writing
+ * - No真实 subagent 调用
+ * - Deterministic based on inputs (no random selection)
+ *
+ * OUTPUT: NocturnalSelectionResult with:
+ * - decision: 'selected' | 'skip'
+ * - selectedPrincipleId?: string
+ * - selectedSessionId?: string
+ * - skipReason?: SkipReason
+ * - diagnostics: scoring and filtering details
+ */
+import { NocturnalTrajectoryExtractor } from '../core/nocturnal-trajectory-extractor.js';
+import { type IdleCheckResult } from './nocturnal-runtime.js';
+export type SkipReason = 'no_evaluable_principles' | 'all_targets_in_cooldown' | 'no_violating_sessions' | 'workspace_not_idle' | 'quota_exhausted' | 'insufficient_snapshot_data' | 'global_cooldown_active';
+export interface SelectionDiagnostics {
+    /** Total evaluable principles found */
+    totalEvaluablePrinciples: number;
+    /** Principles filtered out by cooldown */
+    filteredByCooldown: number;
+    /** Principles that passed all filters */
+    passedPrinciples: string[];
+    /** Violating sessions found for selected principle */
+    violatingSessionCount: number;
+    /** Violation density of selected session (failures / total tool calls) */
+    selectedSessionViolationDensity: number | null;
+    /** Score of selected principle */
+    selectedPrincipleScore: number | null;
+    /** Score breakdown */
+    scoringBreakdown: Record<string, number>;
+    /** Whether workspace idle check passed */
+    idleCheckPassed: boolean;
+    /** Whether cooldown check passed */
+    cooldownCheckPassed: boolean;
+    /** Whether quota check passed */
+    quotaCheckPassed: boolean;
+    /** Recent pain context used for ranking bias (if available) */
+    painContext?: {
+        recentPainCount: number;
+        recentMaxPainScore: number;
+        hasRecentPain: boolean;
+        painSource?: string;
+    };
+}
+export interface NocturnalSelectionResult {
+    /** Whether a target was selected */
+    decision: 'selected' | 'skip';
+    /** Selected principle ID (if decision === 'selected') */
+    selectedPrincipleId?: string;
+    /** Selected violating session ID (if decision === 'selected') */
+    selectedSessionId?: string;
+    /** Reason for skip (if decision === 'skip') */
+    skipReason?: SkipReason;
+    /** Detailed diagnostics for observability */
+    diagnostics: SelectionDiagnostics;
+}
+export interface NocturnalTargetSelectorOptions {
+    /**
+     * Minimum violation density threshold for a session to be considered "violating".
+     * Default: 0.1 (at least 10% of tool calls are violation signals)
+     */
+    minViolationDensity?: number;
+    /**
+     * Maximum number of recent sessions to consider for violation matching.
+     * Default: 50
+     */
+    maxSessionCandidates?: number;
+    /**
+     * Idle threshold override (ms).
+     * Default: from nocturnal-runtime DEFAULT_IDLE_THRESHOLD_MS
+     */
+    idleThresholdMs?: number;
+    /**
+     * Override idle check result (for testing).
+     * If provided, this result is used instead of calling checkWorkspaceIdle.
+     */
+    idleCheckOverride?: IdleCheckResult;
+    /**
+     * Recent pain context from evolution worker.
+     * When provided, principles related to recent pain signals get ranking bias.
+     * This threads recent pain into sleep_reflection targeting without merging task kinds.
+     */
+    recentPainContext?: {
+        mostRecent: {
+            score: number;
+            source: string;
+            reason: string;
+            timestamp: string;
+        } | null;
+        recentPainCount: number;
+        recentMaxPainScore: number;
+    };
+}
+/**
+ * Nocturnal Target Selector.
+ *
+ * Selects one target principle and one violating session for nocturnal reflection.
+ * This is a PURE FUNCTION — no side effects, no artifact writing.
+ */
+export declare class NocturnalTargetSelector {
+    private readonly extractor;
+    private readonly stateDir;
+    private readonly workspaceDir;
+    private readonly opts;
+    private readonly idleCheckOverride?;
+    private readonly recentPainContext?;
+    constructor(workspaceDir: string, stateDir: string, extractor: NocturnalTrajectoryExtractor, options?: NocturnalTargetSelectorOptions);
+    /**
+     * Select a target principle and violating session.
+     *
+     * @returns NocturnalSelectionResult with either selected targets or skip reason
+     */
+    select(): NocturnalSelectionResult;
+}
+/**
+ * Select a nocturnal target (principle + session) with default options.
+ *
+ * This is a convenience wrapper for the common case.
+ */
+export declare function selectNocturnalTarget(workspaceDir: string, stateDir: string, extractor: NocturnalTrajectoryExtractor, options?: NocturnalTargetSelectorOptions): NocturnalSelectionResult;

package/dist/service/nocturnal-target-selector.js

@@ -0,0 +1,315 @@
+/**
+ * Nocturnal Target Selector — Principle + Session Selection for Sleep-Mode Reflection
+ * ================================================================================
+ *
+ * PURPOSE: Select one target principle and one violating session for nocturnal
+ * reflection processing. This module is a PURE SELECTOR — it does NOT execute
+ * reflection or write any artifacts.
+ *
+ * SELECTION LOGIC:
+ * 1. Filter principles to evaluable candidates (not manual_only, not cooldown)
+ * 2. Score candidates by: compliance health, violation trend, sample scarcity
+ * 3. Select top principle
+ * 4. Find violating sessions for that principle
+ * 5. Select best violating session by violation density
+ *
+ * SKIP CONDITIONS (return no-op cleanly):
+ * - no_evaluable_principles: No principles with auto-trainable evaluability
+ * - all_targets_in_cooldown: All candidates are in cooldown
+ * - no_violating_sessions: No sessions show violation signals for selected principle
+ * - workspace_not_idle: Workspace is active, nocturnal run not allowed
+ * - quota_exhausted: Max runs per window reached
+ * - insufficient_snapshot_data: Sessions exist but lack tool calls
+ *
+ * DESIGN CONSTRAINTS:
+ * - This is a PURE SELECTOR — no reflection execution
+ * - No raw text exposure
+ * - No artifact writing
+ * - No真实 subagent 调用
+ * - Deterministic based on inputs (no random selection)
+ *
+ * OUTPUT: NocturnalSelectionResult with:
+ * - decision: 'selected' | 'skip'
+ * - selectedPrincipleId?: string
+ * - selectedSessionId?: string
+ * - skipReason?: SkipReason
+ * - diagnostics: scoring and filtering details
+ */
+import { listEvaluablePrinciples, } from '../core/principle-training-state.js';
+import { checkWorkspaceIdle, checkCooldown, DEFAULT_IDLE_THRESHOLD_MS, } from './nocturnal-runtime.js';
+import { detectViolation } from '../core/nocturnal-compliance.js';
+/**
+ * Score a principle for nocturnal targeting.
+ * Higher score = better candidate for reflection.
+ *
+ * Scoring dimensions:
+ * 1. Compliance health (higher compliance = more worth teaching)
+ * 2. Violation trend (worsening trend = higher priority)
+ * 3. Sample scarcity (fewer samples = more valuable)
+ * 4. Cooldown penalty (in cooldown = lower priority)
+ * 5. Pain context bias (recent pain = higher priority for related principles)
+ *
+ * Score range: 0-100 (normalized)
+ */
+function scorePrinciple(state, cooldownActive, recentPainContext) {
+    let score = 50; // Base score
+    // Compliance contribution: 0-25 points
+    // High compliance = well-understood principle = good teaching target
+    // But very low compliance = confused principle = also needs work
+    const complianceContribution = Math.round(state.complianceRate * 25);
+    score += complianceContribution;
+    // Trend contribution: -10 to +10 points
+    // worsening trend (+1) = higher priority = +10
+    // improving trend (-1) = lower priority = -10
+    // stable (0) = neutral = 0
+    score += state.violationTrend * 10;
+    // Sample scarcity contribution: 0-15 points
+    // Fewer samples generated = more valuable new data
+    // Max at 0 samples, decreases as samples accumulate
+    const scarcityPenalty = Math.min(state.generatedSampleCount / 10, 1) * 15;
+    score += Math.round(15 - scarcityPenalty);
+    // Cooldown penalty: -30 points
+    if (cooldownActive) {
+        score -= 30;
+    }
+    // Pain context bias: up to +25 points
+    // Bias toward principles related to recent pain signals
+    if (recentPainContext && recentPainContext.recentPainCount > 0) {
+        // Most recent pain score contributes up to 15 points (pain scores are 1-10)
+        const mostRecentPainScore = recentPainContext.mostRecent?.score ?? 0;
+        const painScoreContribution = Math.round((mostRecentPainScore / 10) * 15);
+        score += painScoreContribution;
+        // Additional pain count adds up to 5 more points
+        const additionalPainContribution = Math.min(recentPainContext.recentPainCount - 1, 5) * 1;
+        score += additionalPainContribution;
+        // High pain scores (> 7) get extra 5-point boost
+        if (recentPainContext.recentMaxPainScore > 7) {
+            score += 5;
+        }
+    }
+    return Math.max(0, Math.min(100, score));
+}
+/**
+ * Compute violation signal density for a session.
+ * Returns 0-1 score (higher = more violation evidence).
+ */
+function computeViolationDensity(session) {
+    const total = session.toolCallCount;
+    if (total === 0)
+        return 0;
+    // Violation signals: failures, pain events, gate blocks
+    const violationSignals = session.failureCount + session.painEventCount * 0.5 + session.gateBlockCount * 0.3;
+    return Math.min(violationSignals / total, 1);
+}
+/**
+ * Nocturnal Target Selector.
+ *
+ * Selects one target principle and one violating session for nocturnal reflection.
+ * This is a PURE FUNCTION — no side effects, no artifact writing.
+ */
+export class NocturnalTargetSelector {
+    extractor;
+    stateDir;
+    workspaceDir;
+    opts;
+    idleCheckOverride;
+    recentPainContext;
+    constructor(workspaceDir, stateDir, extractor, options = {}) {
+        this.workspaceDir = workspaceDir;
+        this.stateDir = stateDir;
+        this.extractor = extractor;
+        // Destructure so they are NOT included in opts (stored separately)
+        const { idleCheckOverride, recentPainContext, ...restOptions } = options;
+        this.idleCheckOverride = idleCheckOverride;
+        this.recentPainContext = recentPainContext;
+        this.opts = {
+            minViolationDensity: restOptions.minViolationDensity ?? 0.1,
+            maxSessionCandidates: restOptions.maxSessionCandidates ?? 50,
+            idleThresholdMs: restOptions.idleThresholdMs ?? DEFAULT_IDLE_THRESHOLD_MS,
+        };
+    }
+    /**
+     * Select a target principle and violating session.
+     *
+     * @returns NocturnalSelectionResult with either selected targets or skip reason
+     */
+    select() {
+        const diagnostics = {
+            totalEvaluablePrinciples: 0,
+            filteredByCooldown: 0,
+            passedPrinciples: [],
+            violatingSessionCount: 0,
+            selectedSessionViolationDensity: null,
+            selectedPrincipleScore: null,
+            scoringBreakdown: {},
+            idleCheckPassed: false,
+            cooldownCheckPassed: false,
+            quotaCheckPassed: false,
+            painContext: this.recentPainContext ? {
+                recentPainCount: this.recentPainContext.recentPainCount,
+                recentMaxPainScore: this.recentPainContext.recentMaxPainScore,
+                hasRecentPain: this.recentPainContext.recentPainCount > 0,
+                painSource: this.recentPainContext.mostRecent?.source,
+            } : undefined,
+        };
+        // Step 1: Idle check — if workspace is not idle, skip
+        const idleResult = this.idleCheckOverride ?? checkWorkspaceIdle(this.workspaceDir, {
+            idleThresholdMs: this.opts.idleThresholdMs,
+        });
+        diagnostics.idleCheckPassed = idleResult.isIdle;
+        if (!idleResult.isIdle) {
+            return {
+                decision: 'skip',
+                skipReason: 'workspace_not_idle',
+                diagnostics,
+            };
+        }
+        // Step 2: Cooldown and quota check
+        const cooldownResult = checkCooldown(this.stateDir);
+        diagnostics.cooldownCheckPassed = !cooldownResult.globalCooldownActive;
+        diagnostics.quotaCheckPassed = !cooldownResult.quotaExhausted;
+        if (cooldownResult.globalCooldownActive) {
+            return {
+                decision: 'skip',
+                skipReason: 'global_cooldown_active',
+                diagnostics,
+            };
+        }
+        if (cooldownResult.quotaExhausted) {
+            return {
+                decision: 'skip',
+                skipReason: 'quota_exhausted',
+                diagnostics,
+            };
+        }
+        // Step 3: Get evaluable principles
+        const evaluablePrinciples = listEvaluablePrinciples(this.stateDir);
+        diagnostics.totalEvaluablePrinciples = evaluablePrinciples.length;
+        if (evaluablePrinciples.length === 0) {
+            return {
+                decision: 'skip',
+                skipReason: 'no_evaluable_principles',
+                diagnostics,
+            };
+        }
+        // Step 4: Score and filter candidates
+        const scoredPrinciples = [];
+        for (const state of evaluablePrinciples) {
+            const cooldownCheck = checkCooldown(this.stateDir, state.principleId);
+            const cooldownActive = cooldownCheck.principleCooldownActive;
+            const score = scorePrinciple(state, cooldownActive, this.recentPainContext);
+            if (cooldownActive) {
+                diagnostics.filteredByCooldown++;
+            }
+            scoredPrinciples.push({
+                principleId: state.principleId,
+                state,
+                score,
+                violationDensity: state.applicableOpportunityCount > 0
+                    ? state.observedViolationCount / state.applicableOpportunityCount
+                    : 0,
+                cooldownActive,
+            });
+            diagnostics.scoringBreakdown[state.principleId] = score;
+        }
+        // Filter out principles in cooldown (score already penalized but keep them in diagnostics)
+        const activeCandidates = scoredPrinciples.filter((p) => !p.cooldownActive);
+        if (activeCandidates.length === 0) {
+            diagnostics.passedPrinciples = [];
+            return {
+                decision: 'skip',
+                skipReason: 'all_targets_in_cooldown',
+                diagnostics,
+            };
+        }
+        // Sort by score descending
+        activeCandidates.sort((a, b) => b.score - a.score);
+        diagnostics.passedPrinciples = activeCandidates.map((p) => p.principleId);
+        // Select the top candidate
+        const selected = activeCandidates[0];
+        diagnostics.selectedPrincipleScore = selected.score;
+        // Step 5: Find violating sessions for the selected principle
+        const recentSessions = this.extractor.listRecentNocturnalCandidateSessions({
+            limit: this.opts.maxSessionCandidates,
+            minToolCalls: 1,
+        });
+        if (recentSessions.length === 0) {
+            return {
+                decision: 'skip',
+                skipReason: 'insufficient_snapshot_data',
+                diagnostics,
+            };
+        }
+        // Compute violation signals for each session
+        const violatingSessions = recentSessions.map((session) => {
+            const violationDensity = computeViolationDensity(session);
+            const snapshot = this.extractor.getNocturnalSessionSnapshot(session.sessionId);
+            // Use nocturnal-compliance to detect violations for the selected principle
+            let hasViolation = false;
+            if (snapshot) {
+                const violationResult = detectViolation(selected.principleId, {
+                    sessionId: session.sessionId,
+                    toolCalls: snapshot.toolCalls.map((tc) => ({
+                        toolName: tc.toolName,
+                        filePath: tc.filePath ?? undefined,
+                        outcome: tc.outcome,
+                        errorMessage: tc.errorMessage ?? undefined,
+                    })),
+                    painSignals: snapshot.painEvents.map((pe) => ({
+                        source: pe.source,
+                        score: pe.score,
+                        reason: pe.reason ?? undefined,
+                    })),
+                    gateBlocks: snapshot.gateBlocks.map((gb) => ({
+                        toolName: gb.toolName,
+                        reason: gb.reason,
+                    })),
+                    userCorrections: [],
+                    planApprovals: [],
+                });
+                hasViolation = violationResult.violated;
+            }
+            return {
+                sessionId: session.sessionId,
+                hasViolation,
+                violationSeverity: violationDensity,
+                failureCount: session.failureCount,
+                painEventCount: session.painEventCount,
+                gateBlockCount: session.gateBlockCount,
+                toolCallCount: session.toolCallCount,
+            };
+        });
+        // Filter to sessions with violations above threshold
+        const violating = violatingSessions.filter((s) => s.hasViolation && s.violationSeverity >= this.opts.minViolationDensity);
+        diagnostics.violatingSessionCount = violating.length;
+        if (violating.length === 0) {
+            return {
+                decision: 'skip',
+                skipReason: 'no_violating_sessions',
+                diagnostics,
+            };
+        }
+        // Sort by violation severity descending (most violating first)
+        violating.sort((a, b) => b.violationSeverity - a.violationSeverity);
+        const selectedSession = violating[0];
+        diagnostics.selectedSessionViolationDensity = selectedSession.violationSeverity;
+        return {
+            decision: 'selected',
+            selectedPrincipleId: selected.principleId,
+            selectedSessionId: selectedSession.sessionId,
+            diagnostics,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Convenience function
+// ---------------------------------------------------------------------------
+/**
+ * Select a nocturnal target (principle + session) with default options.
+ *
+ * This is a convenience wrapper for the common case.
+ */
+export function selectNocturnalTarget(workspaceDir, stateDir, extractor, options = {}) {
+    const selector = new NocturnalTargetSelector(workspaceDir, stateDir, extractor, options);
+    return selector.select();
+}

package/dist/service/phase3-input-filter.d.ts

@@ -1,13 +1,33 @@
+/**
+ * Phase 3 Input Filter
+ *
+ * CRITICAL: evaluatePhase3Inputs() does NOT read or use evolution_directive.json
+ * Directive is a compatibility-only display artifact, not a truth source.
+ *
+ * Phase 3 eligibility depends ONLY on:
+ * - Queue truth (valid evolution samples from queue)
+ *
+ * Any directive file is ignored for eligibility decisions.
+ *
+ * THREE-LANE CLASSIFICATION:
+ * - authoritative: Valid inputs that can be used for Phase 3 eligibility decisions
+ * - reference_only: Valid evidence that must NOT be used as positive eligibility input
+ *   (e.g., timeout-only outcomes - they indicate completion but not success)
+ * - rejected: Invalid, corrupt, or policy-prohibited input
+ */
+/**
+ * Classification for Phase 3 inputs.
+ * - authoritative: Can be used for Phase 3 eligibility decisions
+ * - reference_only: Valid data but not for eligibility (e.g., timeout outcomes)
+ * - rejected: Invalid or corrupt data
+ */
+export type Phase3Classification = 'authoritative' | 'reference_only' | 'rejected';
 export interface Phase3EvolutionInput {
     id?: string | null;
     status?: string | null;
     started_at?: string | null;
     completed_at?: string | null;
-}
-export interface Phase3TrustInput {
-    score?: number | null;
-    frozen?: boolean | null;
-    lastUpdated?: string | null;
+    resolution?: string | null;
 }
 export interface Phase3EvolutionSample {
     taskId: string;
@@ -15,23 +35,39 @@ export interface Phase3EvolutionSample {
     startedAt: string | null;
     completedAt: string | null;
 }
+export interface Phase3ReferenceOnlySample {
+    taskId: string;
+    status: string;
+    classification: 'timeout_only' | 'other_reference';
+    reason: string;
+}
 export interface Phase3RejectedEvolutionSample {
     taskId: string | null;
     status: string | null;
     reasons: string[];
 }
-export interface Phase3TrustResult {
-    eligible: boolean;
-    rejectedReasons: string[];
-}
 export interface Phase3InputFilterResult {
     queueTruthReady: boolean;
-    trustInputReady: boolean;
     phase3ShadowEligible: boolean;
     evolution: {
         eligible: Phase3EvolutionSample[];
+        referenceOnly: Phase3ReferenceOnlySample[];
         rejected: Phase3RejectedEvolutionSample[];
     };
-    trust: Phase3TrustResult;
 }
-export declare function evaluatePhase3Inputs(queue: Phase3EvolutionInput[], trust: Phase3TrustInput): Phase3InputFilterResult;
+/**
+ * Evaluates Phase 3 readiness based on queue inputs.
+ *
+ * IMPORTANT: Does NOT use evolution_directive.json.
+ * Directive is compatibility-only display artifact, not a truth source.
+ * Queue is the only authoritative execution truth source for Phase 3.
+ *
+ * THREE-LANE CLASSIFICATION:
+ * - authoritative: Valid inputs for Phase 3 eligibility
+ * - reference_only: Valid evidence but not for eligibility (e.g., timeout outcomes)
+ * - rejected: Invalid, corrupt, or policy-prohibited input
+ *
+ * @param queue - Evolution queue items to validate
+ * @returns Phase 3 eligibility results
+ */
+export declare function evaluatePhase3Inputs(queue: Phase3EvolutionInput[]): Phase3InputFilterResult;