principles-disciple 1.7.6 → 1.7.8

package/dist/core/nocturnal-candidate-scoring.js

@@ -0,0 +1,266 @@
+/**
+ * Nocturnal Candidate Scoring — Deterministic Tournament Selection
+ * ============================================================
+ *
+ * PURPOSE: Score Trinity candidates and run deterministic tournament selection
+ * to choose the best candidate for artifact generation.
+ *
+ * DESIGN CONSTRAINTS:
+ * - Scoring is deterministic: same inputs → same winner
+ * - Tie-break rules are stable and explicit
+ * - No randomness in ranking or selection
+ * - Winner is always the highest-scoring candidate
+ * - Thresholds provide minimum quality gates
+ * - Failed threshold candidates are excluded from tournament
+ *
+ * SCORING COMPONENTS:
+ * - schema completeness: candidate has all required fields
+ * - principle alignment: candidate aligns with target principle
+ * - executability: candidate describes an actionable next step
+ * - boundedness: candidate is specific and bounded
+ * - confidence/consistency: candidate's internal consistency
+ *
+ * PHASE 6 ONLY — No real training, no automatic deployment
+ */
+/**
+ * Default scoring weights (must sum to 1.0).
+ */
+export const DEFAULT_SCORING_WEIGHTS = {
+    schemaCompleteness: 0.15,
+    principleAlignment: 0.30,
+    executability: 0.20,
+    boundedness: 0.20,
+    confidence: 0.15,
+};
+// ---------------------------------------------------------------------------
+// Scoring Logic
+// ---------------------------------------------------------------------------
+/**
+ * Score a single Dreamer candidate + Philosopher judgment pair.
+ *
+ * @param candidate - Dreamer candidate
+ * @param judgment - Philosopher judgment
+ * @param weights - Scoring weights
+ * @returns Individual scores
+ */
+export function scoreCandidate(candidate, judgment, weights = DEFAULT_SCORING_WEIGHTS) {
+    // Schema completeness: all required fields present and non-empty
+    let schemaCompleteness = 1.0;
+    if (!candidate.badDecision || candidate.badDecision.trim().length === 0)
+        schemaCompleteness -= 0.2;
+    if (!candidate.betterDecision || candidate.betterDecision.trim().length === 0)
+        schemaCompleteness -= 0.2;
+    if (!candidate.rationale || candidate.rationale.trim().length === 0)
+        schemaCompleteness -= 0.2;
+    if (typeof candidate.confidence !== 'number' || candidate.confidence < 0 || candidate.confidence > 1)
+        schemaCompleteness -= 0.2;
+    if (candidate.badDecision && candidate.betterDecision && candidate.badDecision.trim() === candidate.betterDecision.trim())
+        schemaCompleteness -= 0.2;
+    schemaCompleteness = Math.max(0, schemaCompleteness);
+    // Principle alignment: from Philosopher judgment
+    const principleAlignment = judgment.principleAligned ? 1.0 : 0.3;
+    // Executability: betterDecision contains actionable verb
+    const actionableVerbs = ['read', 'check', 'verify', 'edit', 'write', 'search', 'grep', 'review', 'analyze', 'diagnose', 'debug', 'inspect', 'examine', 'test'];
+    const hasActionableVerb = candidate.betterDecision
+        ? actionableVerbs.some((v) => candidate.betterDecision.toLowerCase().includes(v))
+        : false;
+    const executability = hasActionableVerb ? 1.0 : 0.4;
+    // Boundedness: specific and constrained
+    let boundedness = 0.5;
+    // Specific: mentions specific targets (files, tools, etc.)
+    const betterDecisionStr = candidate.betterDecision ?? '';
+    const hasSpecificTarget = /[a-zA-Z0-9_\-]+\.(ts|js|json|md|yml|yaml|sh|py|go|rs)/.test(betterDecisionStr);
+    if (hasSpecificTarget)
+        boundedness += 0.2;
+    // Not too generic
+    const genericPatterns = [
+        /\bsomething\b/i,
+        /\bsomething else\b/i,
+        /\bit\b/i,
+        /\bthe thing\b/i,
+    ];
+    const isGeneric = genericPatterns.some((pattern) => pattern.test(betterDecisionStr));
+    if (isGeneric)
+        boundedness -= 0.3;
+    // Not too long (如果 multi-step vagueness)
+    if (betterDecisionStr.length > 200)
+        boundedness -= 0.1;
+    boundedness = Math.max(0, Math.min(1, boundedness));
+    // Confidence: from Dreamer's confidence, adjusted by consistency
+    const baseConfidence = typeof candidate.confidence === 'number' ? candidate.confidence : 0.5;
+    // Slight consistency check: Philosopher score should correlate with confidence
+    const consistency = 1.0 - Math.abs(baseConfidence - judgment.score);
+    const confidence = baseConfidence * 0.7 + consistency * 0.3;
+    // Calculate aggregate
+    const aggregate = schemaCompleteness * weights.schemaCompleteness +
+        principleAlignment * weights.principleAlignment +
+        executability * weights.executability +
+        boundedness * weights.boundedness +
+        confidence * weights.confidence;
+    return {
+        schemaCompleteness: Math.round(schemaCompleteness * 100) / 100,
+        principleAlignment: Math.round(principleAlignment * 100) / 100,
+        executability: Math.round(executability * 100) / 100,
+        boundedness: Math.round(boundedness * 100) / 100,
+        confidence: Math.round(confidence * 100) / 100,
+        aggregate: Math.round(aggregate * 100) / 100,
+    };
+}
+/**
+ * Check if candidate passes minimum thresholds.
+ *
+ * @param scores - Candidate scores
+ * @param thresholds - Minimum threshold values
+ * @returns Tuple of [passed, failedThresholdNames]
+ */
+export function checkThresholds(scores, thresholds) {
+    const failedThresholds = [];
+    if (scores.schemaCompleteness < thresholds.schemaCompletenessMin) {
+        failedThresholds.push(`schemaCompleteness (${scores.schemaCompleteness} < ${thresholds.schemaCompletenessMin})`);
+    }
+    if (scores.principleAlignment < thresholds.principleAlignmentMin) {
+        failedThresholds.push(`principleAlignment (${scores.principleAlignment} < ${thresholds.principleAlignmentMin})`);
+    }
+    if (scores.executability < thresholds.executabilityMin) {
+        failedThresholds.push(`executability (${scores.executability} < ${thresholds.executabilityMin})`);
+    }
+    if (scores.boundedness < thresholds.boundednessMin) {
+        failedThresholds.push(`boundedness (${scores.boundedness} < ${thresholds.boundednessMin})`);
+    }
+    if (scores.confidence < thresholds.confidenceMin) {
+        failedThresholds.push(`confidence (${scores.confidence} < ${thresholds.confidenceMin})`);
+    }
+    if (scores.aggregate < thresholds.aggregateMin) {
+        failedThresholds.push(`aggregate (${scores.aggregate} < ${thresholds.aggregateMin})`);
+    }
+    return [failedThresholds.length === 0, failedThresholds];
+}
+/**
+ * Score and rank all candidates deterministically.
+ *
+ * @param candidates - Dreamer candidates
+ * @param judgments - Philosopher judgments (aligned by candidateIndex)
+ * @param thresholds - Minimum thresholds
+ * @param weights - Scoring weights
+ * @returns All scored and ranked candidates
+ */
+export function rankCandidates(candidates, judgments, thresholds, weights = DEFAULT_SCORING_WEIGHTS) {
+    const trace = [];
+    trace.push({
+        step: 'Input Validation',
+        details: `Received ${candidates.length} candidates and ${judgments.length} judgments`,
+    });
+    // Score each candidate
+    const scored = [];
+    for (const candidate of candidates) {
+        const judgment = judgments.find((j) => j.candidateIndex === candidate.candidateIndex);
+        if (!judgment) {
+            trace.push({
+                step: `Candidate ${candidate.candidateIndex}`,
+                details: 'Skipped - no matching judgment found',
+            });
+            continue;
+        }
+        const scores = scoreCandidate(candidate, judgment, weights);
+        const [passed, failed] = checkThresholds(scores, thresholds);
+        scored.push({
+            candidateIndex: candidate.candidateIndex,
+            candidate,
+            judgment,
+            scores,
+            rank: 0, // Will be set after sorting
+            thresholdPassed: passed,
+            failedThresholds: failed,
+        });
+        trace.push({
+            step: `Candidate ${candidate.candidateIndex} Scored`,
+            details: `aggregate=${scores.aggregate.toFixed(2)}, thresholdPassed=${passed}`,
+        });
+    }
+    // Sort by: thresholdPassed DESC, aggregate DESC, candidateIndex ASC (for stability)
+    scored.sort((a, b) => {
+        // Threshold-passed candidates come first
+        if (a.thresholdPassed !== b.thresholdPassed) {
+            return a.thresholdPassed ? -1 : 1;
+        }
+        // Higher aggregate score wins
+        if (a.scores.aggregate !== b.scores.aggregate) {
+            return b.scores.aggregate - a.scores.aggregate;
+        }
+        // Lower candidateIndex wins ties (stability)
+        return a.candidateIndex - b.candidateIndex;
+    });
+    // Assign ranks
+    let currentRank = 1;
+    let currentAggregate = -1;
+    for (const candidate of scored) {
+        if (candidate.scores.aggregate !== currentAggregate) {
+            currentRank = scored.indexOf(candidate) + 1;
+            currentAggregate = candidate.scores.aggregate;
+        }
+        candidate.rank = currentRank;
+    }
+    trace.push({
+        step: 'Ranking Complete',
+        details: `Final order: ${scored.map((c) => `C${c.candidateIndex}(rank=${c.rank},agg=${c.scores.aggregate.toFixed(2)})`).join(', ')}`,
+    });
+    return scored;
+}
+/**
+ * Run tournament selection to choose the best candidate.
+ *
+ * @param candidates - Dreamer candidates
+ * @param judgments - Philosopher judgments
+ * @param thresholds - Minimum thresholds
+ * @param weights - Scoring weights
+ * @returns Tournament result with winner
+ */
+export function runTournament(candidates, judgments, thresholds, weights = DEFAULT_SCORING_WEIGHTS) {
+    const trace = [];
+    if (candidates.length === 0 || judgments.length === 0) {
+        return {
+            success: false,
+            winner: null,
+            rankedCandidates: [],
+            trace: [{ step: 'Validation', details: 'No candidates or judgments provided' }],
+            failureReason: 'No candidates or judgments provided',
+        };
+    }
+    trace.push({
+        step: 'Tournament Start',
+        details: `${candidates.length} candidates in tournament`,
+    });
+    // Rank candidates
+    const ranked = rankCandidates(candidates, judgments, thresholds, weights);
+    trace.push({
+        step: 'Threshold Check',
+        details: `${ranked.filter((c) => c.thresholdPassed).length} candidates passed thresholds`,
+    });
+    // Filter to threshold-passed candidates for winner determination
+    const eligible = ranked.filter((c) => c.thresholdPassed);
+    if (eligible.length === 0) {
+        trace.push({
+            step: 'No Winner',
+            details: 'All candidates failed threshold check',
+        });
+        return {
+            success: false,
+            winner: null,
+            rankedCandidates: ranked,
+            trace,
+            failureReason: 'All candidates failed threshold check',
+        };
+    }
+    // Winner is rank 1
+    const winner = eligible[0];
+    trace.push({
+        step: 'Winner Selected',
+        details: `Candidate ${winner.candidateIndex} wins with aggregate score ${winner.scores.aggregate.toFixed(2)}`,
+    });
+    return {
+        success: true,
+        winner,
+        rankedCandidates: ranked,
+        trace,
+    };
+}

package/dist/core/nocturnal-compliance.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Nocturnal Compliance Engine — Opportunity-Based Principle Evaluation
+ * =====================================================================
+ *
+ * Replaces session-average compliance with opportunity-based compliance.
+ *
+ * CORE CONCEPTS:
+ *
+ * Opportunity — a session context where a principle COULD have been applied.
+ *                An opportunity exists when the agent's action (or planned action)
+ *                falls within the principle's applicability scope.
+ *
+ * Compliance   — the principle was followed in an opportunity.
+ *                Determined by absence of violation signals, not presence of
+ *                positive confirmation (avoids LLM scoring).
+ *
+ * Violation   — strong evidence the principle was NOT followed.
+ *                Detected through deterministic event signals (pain, tool failures,
+ *                gate blocks) — no LLM involved.
+ *
+ * Dilution prevention — compliance is computed ONLY over sessions where the
+ *                         principle had an opportunity. Unrelated sessions
+ *                         (where T-05's risky operations never occurred) do NOT
+ *                         dilute the compliance rate.
+ *
+ * DESIGN CONSTRAINTS (Phase 1):
+ * - T-xx principles only (deterministic / weak-heuristic evaluability)
+ * - No P_xxx automation (requires detector metadata — Task 1.3 scope)
+ * - No LLM-based scoring
+ * - No training logic
+ *
+ * FILE: No file persistence — stateless computation over event stream.
+ *       Caller is responsible for writing results to principle-training-state.ts.
+ */
+/**
+ * Session events extracted from the event log.
+ * Compatible with EventLogEntry from event-types.ts.
+ */
+export interface SessionEvents {
+    sessionId: string;
+    toolCalls: ToolCallRecord[];
+    painSignals: PainSignalRecord[];
+    gateBlocks: GateBlockRecord[];
+    userCorrections: UserCorrectionRecord[];
+    planApprovals: PlanApprovalRecord[];
+}
+export interface ToolCallRecord {
+    toolName: string;
+    filePath?: string;
+    outcome: 'success' | 'failure' | 'blocked';
+    errorType?: string;
+    errorMessage?: string;
+}
+export interface PainSignalRecord {
+    source: string;
+    score: number;
+    severity?: 'mild' | 'moderate' | 'severe';
+    reason?: string;
+}
+export interface GateBlockRecord {
+    toolName: string;
+    filePath?: string;
+    reason: string;
+}
+export interface UserCorrectionRecord {
+    correctionCue?: string;
+}
+export interface PlanApprovalRecord {
+    toolName: string;
+    filePath?: string;
+}
+/**
+ * The result of compliance computation for one principle.
+ */
+export interface ComplianceResult {
+    principleId: string;
+    /** Number of sessions/events where this principle had an applicable opportunity */
+    applicableOpportunityCount: number;
+    /** Number of opportunities where violation signals were detected */
+    observedViolationCount: number;
+    /** complianceRate = (opportunities - violations) / opportunities; 0 if none */
+    complianceRate: number;
+    /**
+     * Violation trend:
+     *   +1 = violations increasing (worsening)
+     *    0 = stable
+     *   -1 = violations decreasing (improving)
+     */
+    violationTrend: number;
+    /**
+     * Explanation of why the result is what it is.
+     * For debugging, observability, and reviewer verification.
+     */
+    explanation: string;
+}
+/**
+ * Opportunity detection result for a single session.
+ */
+interface OpportunityMatch {
+    applicable: boolean;
+    reason: string;
+}
+/**
+ * Violation detection result for a session with applicable opportunity.
+ */
+interface ViolationMatch {
+    violated: boolean;
+    reason: string;
+}
+/**
+ * Detects whether a given session presents an APPLICABLE OPPORTUNITY
+ * for a specific T-xx principle.
+ *
+ * An opportunity exists when the session context falls within the
+ * principle's applicability scope — regardless of whether the agent
+ * followed the principle.
+ *
+ * IMPORTANT: This does NOT assess compliance. It only answers:
+ *   "Could the principle have applied here?"
+ */
+export declare function detectOpportunity(principleId: string, session: SessionEvents): OpportunityMatch;
+/**
+ * Detects whether a principle was VIOLATED in a session where an
+ * opportunity was applicable.
+ *
+ * Returns a ViolationMatch with violated=true if violation signals are present.
+ */
+export declare function detectViolation(principleId: string, session: SessionEvents): ViolationMatch;
+/**
+ * Computes compliance metrics for a single T-xx principle across a batch of sessions.
+ *
+ * DILUTION PREVENTION:
+ * - Sessions where the principle had NO opportunity are EXCLUDED from
+ *   applicableOpportunityCount and do not affect complianceRate.
+ * - Example: T-05 sessions with no risky operations do not dilute
+ *   the compliance rate computed from T-05 sessions with gate blocks.
+ *
+ * TREND COMPUTATION:
+ * - Sessions are ordered chronologically (most recent first).
+ * - Current window: last 3 applicable sessions.
+ * - Previous window: sessions 4-6 (if available).
+ * - If either window has < 1 applicable session, trend = 0 (insufficient data).
+ * - Otherwise: trend = prevViolationRate - currentViolationRate
+ *   (+1 = improving, 0 = stable, -1 = worsening).
+ */
+export declare function computeCompliance(principleId: string, sessions: SessionEvents[], options?: {
+    trendWindowSize?: number;
+}): ComplianceResult;
+/**
+ * Computes compliance results for all T-01 through T-09 principles
+ * across the provided sessions.
+ *
+ * Sessions are assumed to be ordered most-recent-first.
+ */
+export declare function computeAllCompliance(sessions: SessionEvents[], options?: {
+    trendWindowSize?: number;
+}): ComplianceResult[];
+/**
+ * Converts raw EventLogEntry[] from event-types.ts into SessionEvents.
+ *
+ * Groups events by sessionId and maps to the SessionEvents interface.
+ * Events with no sessionId are grouped under sessionId = 'unknown'.
+ */
+export declare function groupEventsIntoSessions(events: RawEventEntry[]): Map<string, SessionEvents>;
+/**
+ * Raw event entry from the events.jsonl log.
+ * Compatible with EventLogEntry from event-types.ts.
+ */
+export interface RawEventEntry {
+    ts: string;
+    type: string;
+    sessionId?: string;
+    data: Record<string, unknown>;
+}
+export {};