principles-disciple 1.8.1 → 1.8.2

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

@@ -1,266 +0,0 @@
-/**
- * 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

@@ -1,175 +0,0 @@
-/**
- * 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 {};