principles-disciple 1.126.0 → 1.128.0

package/dist/core/profile.js

@@ -0,0 +1,211 @@
+export const PROFILE_AUDIT_LEVELS = new Set(["low", "medium", "high"]);
+export const PROFILE_EVOLUTION_MODES = new Set(["realtime", "async"]);
+export const PROFILE_TEST_LEVELS = new Set(["smoke", "unit", "full"]);
+export const PROFILE_DEFAULTS = {
+    audit_level: "medium",
+    risk_paths: [],
+    evolution_mode: "realtime",
+    gate: {
+        require_plan_for_risk_paths: true,
+        require_audit_before_write: true,
+        require_reviewer_after_write: true,
+    },
+    tests: {
+        on_change: "smoke",
+        on_risk_change: "unit",
+        commands: {},
+    },
+    pain: {
+        soft_capture_threshold: 30,
+        adaptive: {
+            enabled: true,
+            spiral_boost: 20,
+            min_threshold: 15,
+            max_threshold: 70,
+            backlog_trigger: 6,
+            hard_failure_trigger: 1,
+            low_recent_success_boost: 15,
+            high_recent_pain_boost: 10,
+        },
+    },
+    lifecycle: {
+        enabled: true,
+        heartbeat_stale_hours: 72,
+    },
+    progressive_gate: {
+        enabled: true,
+        plan_approvals: {
+            enabled: false,
+            max_lines_override: -1,
+            allowed_patterns: [],
+            allowed_operations: [],
+        },
+    },
+    edit_verification: {
+        enabled: true,
+        max_file_size_bytes: 10 * 1024 * 1024, // 10MB
+        fuzzy_match_enabled: true,
+        fuzzy_match_threshold: 0.8,
+        skip_large_file_action: "warn", // "warn" or "block"
+    },
+    thinking_checkpoint: {
+        enabled: false, // Default OFF to avoid blocking new users
+        window_ms: 5 * 60 * 1000, // 5 minute window
+        high_risk_tools: ['run_shell_command', 'delete_file', 'move_file'],
+    },
+    custom_guards: [],
+};
+// Reason: normalizeProfile handles arbitrary JSON profile shapes where static typing cannot capture runtime field existence
+export function normalizeProfile(rawProfile) {
+    const defaults = JSON.parse(JSON.stringify(PROFILE_DEFAULTS));
+    const warnings = [];
+    const normalized = { ...defaults };
+    let invalid = false;
+    if (!rawProfile || typeof rawProfile !== "object" || Array.isArray(rawProfile)) {
+        warnings.push("PROFILE root must be an object; defaults applied.");
+        invalid = true;
+    }
+    else {
+        // Merge known fields (Support both snake_case and camelCase)
+        const auditLevel = rawProfile.audit_level ?? rawProfile.auditLevel;
+        if (PROFILE_AUDIT_LEVELS.has(auditLevel)) {
+            normalized.audit_level = auditLevel;
+        }
+        else if (auditLevel !== undefined) {
+            warnings.push(`Invalid audit_level '${auditLevel}'`);
+        }
+        const evolutionMode = rawProfile.evolution_mode ?? rawProfile.evolutionMode;
+        if (PROFILE_EVOLUTION_MODES.has(evolutionMode)) {
+            normalized.evolution_mode = evolutionMode;
+        }
+        else if (evolutionMode !== undefined) {
+            warnings.push(`Invalid evolution_mode '${evolutionMode}'`);
+        }
+        const riskPaths = rawProfile.risk_paths ?? rawProfile.riskPaths;
+        if (Array.isArray(riskPaths)) {
+            normalized.risk_paths = riskPaths.filter((p) => typeof p === 'string');
+        }
+        else if (typeof riskPaths === 'string') {
+            normalized.risk_paths = [riskPaths];
+        }
+        else if (riskPaths !== undefined) {
+            warnings.push("risk_paths must be an array of strings");
+        }
+        // Gate settings
+        if (rawProfile.gate && typeof rawProfile.gate === 'object') {
+            const g = rawProfile.gate;
+            normalized.gate.require_plan_for_risk_paths = g.require_plan_for_risk_paths ?? g.requirePlanForRiskPaths ?? defaults.gate.require_plan_for_risk_paths;
+            normalized.gate.require_audit_before_write = g.require_audit_before_write ?? g.requireAuditBeforeWrite ?? defaults.gate.require_audit_before_write;
+            normalized.gate.require_reviewer_after_write = g.require_reviewer_after_write ?? g.requireReviewerAfterWrite ?? defaults.gate.require_reviewer_after_write;
+        }
+        // Progressive Gate
+        if (rawProfile.progressive_gate && typeof rawProfile.progressive_gate === 'object') {
+            const pg = rawProfile.progressive_gate;
+            normalized.progressive_gate.enabled = pg.enabled ?? pg.enabled ?? defaults.progressive_gate.enabled;
+            // Plan approvals configuration
+            if (pg.plan_approvals && typeof pg.plan_approvals === 'object') {
+                const pa = pg.plan_approvals;
+                normalized.progressive_gate.plan_approvals.enabled = pa.enabled ?? pa.planApprovals ?? defaults.progressive_gate.plan_approvals.enabled;
+                const maxLines = pa.max_lines_override ?? pa.maxLinesOverride;
+                if (typeof maxLines === 'number' && maxLines >= -1) {
+                    normalized.progressive_gate.plan_approvals.max_lines_override = maxLines;
+                }
+                if (Array.isArray(pa.allowed_patterns)) {
+                    normalized.progressive_gate.plan_approvals.allowed_patterns = pa.allowed_patterns.filter((p) => typeof p === 'string');
+                }
+                if (Array.isArray(pa.allowed_operations)) {
+                    normalized.progressive_gate.plan_approvals.allowed_operations = pa.allowed_operations.filter((o) => typeof o === 'string');
+                }
+            }
+        }
+        else if (rawProfile.progressiveGate && typeof rawProfile.progressiveGate === 'object') {
+            const pg = rawProfile.progressiveGate;
+            normalized.progressive_gate.enabled = pg.enabled ?? defaults.progressive_gate.enabled;
+            // Plan approvals configuration (camelCase)
+            if (pg.planApprovals && typeof pg.planApprovals === 'object') {
+                const pa = pg.planApprovals;
+                normalized.progressive_gate.plan_approvals.enabled = pa.enabled ?? defaults.progressive_gate.plan_approvals.enabled;
+                const maxLines = pa.maxLinesOverride;
+                if (typeof maxLines === 'number' && maxLines >= -1) {
+                    normalized.progressive_gate.plan_approvals.max_lines_override = maxLines;
+                }
+                if (Array.isArray(pa.allowedPatterns)) {
+                    normalized.progressive_gate.plan_approvals.allowed_patterns = pa.allowedPatterns.filter((p) => typeof p === 'string');
+                }
+                if (Array.isArray(pa.allowedOperations)) {
+                    normalized.progressive_gate.plan_approvals.allowed_operations = pa.allowedOperations.filter((o) => typeof o === 'string');
+                }
+            }
+        }
+        // Edit verification settings (P-03)
+        const evRaw = rawProfile.edit_verification ?? rawProfile.editVerification;
+        if (evRaw && typeof evRaw === 'object') {
+            normalized.edit_verification.enabled = evRaw.enabled ?? defaults.edit_verification.enabled;
+            const maxSize = evRaw.max_file_size_bytes ?? evRaw.maxFileSizeBytes;
+            if (typeof maxSize === 'number' && maxSize >= 0) {
+                normalized.edit_verification.max_file_size_bytes = maxSize;
+            }
+            normalized.edit_verification.fuzzy_match_enabled = evRaw.fuzzy_match_enabled ?? evRaw.fuzzyMatchEnabled ?? defaults.edit_verification.fuzzy_match_enabled;
+            const threshold = evRaw.fuzzy_match_threshold ?? evRaw.fuzzyMatchThreshold;
+            if (typeof threshold === 'number' && threshold > 0 && threshold <= 1) {
+                normalized.edit_verification.fuzzy_match_threshold = threshold;
+            }
+            const action = evRaw.skip_large_file_action ?? evRaw.skipLargeFileAction;
+            if (typeof action === 'string' && ['warn', 'block'].includes(action)) {
+                normalized.edit_verification.skip_large_file_action = action;
+            }
+        }
+        // Test settings
+        if (rawProfile.tests && typeof rawProfile.tests === 'object') {
+            const t = rawProfile.tests;
+            const onChange = t.on_change ?? t.onChange;
+            if (PROFILE_TEST_LEVELS.has(onChange)) {
+                normalized.tests.on_change = onChange;
+            }
+            const onRiskChange = t.on_risk_change ?? t.onRiskChange;
+            if (PROFILE_TEST_LEVELS.has(onRiskChange)) {
+                normalized.tests.on_risk_change = onRiskChange;
+            }
+            if (t.commands && typeof t.commands === 'object') {
+                normalized.tests.commands = { ...defaults.tests.commands, ...t.commands };
+            }
+        }
+        // Pain settings
+        if (rawProfile.pain && typeof rawProfile.pain === 'object') {
+            const p = rawProfile.pain;
+            normalized.pain.soft_capture_threshold = p.soft_capture_threshold ?? p.softCaptureThreshold ?? defaults.pain.soft_capture_threshold;
+            if (p.adaptive && typeof p.adaptive === 'object') {
+                normalized.pain.adaptive = { ...defaults.pain.adaptive, ...p.adaptive };
+            }
+        }
+        // Thinking OS Checkpoint settings (P-10)
+        const tcRaw = rawProfile.thinking_checkpoint ?? rawProfile.thinkingCheckpoint;
+        if (tcRaw && typeof tcRaw === 'object') {
+            normalized.thinking_checkpoint.enabled = tcRaw.enabled ?? defaults.thinking_checkpoint.enabled;
+            const windowMs = tcRaw.window_ms ?? tcRaw.windowMs;
+            if (typeof windowMs === 'number' && windowMs > 0) {
+                normalized.thinking_checkpoint.window_ms = windowMs;
+            }
+            if (Array.isArray(tcRaw.high_risk_tools ?? tcRaw.highRiskTools)) {
+                normalized.thinking_checkpoint.high_risk_tools = (tcRaw.high_risk_tools ?? tcRaw.highRiskTools).filter((t) => typeof t === 'string');
+            }
+        }
+        if (Array.isArray(rawProfile.custom_guards)) {
+            normalized.custom_guards = rawProfile.custom_guards.map((item) => {
+                let severity = "error";
+                const itemSeverity = item.severity;
+                if (itemSeverity && ["info", "warning", "error", "fatal"].includes(String(itemSeverity).toLowerCase())) {
+                    severity = String(itemSeverity).toLowerCase();
+                }
+                return {
+                    pattern: String(item.pattern || ""),
+                    message: String(item.message || "Custom guard triggered"),
+                    severity,
+                };
+            }).filter((item) => item.pattern);
+        }
+    }
+    normalized._profile_invalid = invalid;
+    normalized._profile_warnings = warnings;
+    return normalized;
+}

package/dist/core/promotion-gate.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Promotion Gate — Checkpoint Promotion State Machine and Gate Logic
+ * ==================================================================
+ *
+ * PURPOSE: Control when a checkpoint can advance from training → shadow → promotion.
+ * Training success alone is not enough — a checkpoint must prove it improves
+ * bounded worker behavior under the existing offline benchmark and does not
+ * regress runtime safety signals.
+ *
+ * PROMOTION STATES:
+ *   - rejected:         The checkpoint must not be routed
+ *   - candidate_only:  The checkpoint is valid but not yet ready for shadow
+ *   - shadow_ready:   The checkpoint may enter controlled shadow rollout
+ *   - promotable:     The checkpoint may replace the active checkpoint
+ *
+ * STATE TRANSITIONS:
+ *   training_completed
+ *       ↓
+ *   candidate_only  ←── (eval attached, lineage complete)
+ *       ↓
+ *   shadow_ready   ←── (positive delta, safe constraints)
+ *       ↓
+ *   promotable      ←── (shadow window passed, orchestrator review passed)
+ *       ↓
+ *   deployed
+ *
+ * PRIMARY OBJECTIVE:
+ *   maximize reduced_prompt_holdout_delta
+ *
+ * CONSTRAINT METRICS (must all pass for promotion):
+ *   - arbiterRejectRate <= baseline + allowedMargin
+ *   - executabilityRejectRate <= baseline + allowedMargin
+ *   - reviewedSubsetQuality >= baseline
+ *   - routingScopeNotExpanded == true
+ *
+ * DESIGN CONSTRAINTS:
+ *   - No automatic promotion without explicit gate approval
+ *   - Orchestrator review remains mandatory for all promotions
+ *   - Rollback path must be always available
+ *   - First rollout limited to `local-reader` only
+ */
+import { type TrainableWorkerProfile } from './external-training-contract.js';
+/**
+ * Candidate delta must exceed this to enter shadow_ready.
+ */
+export declare const DEFAULT_MIN_DELTA = 0.05;
+/**
+ * Default allowed margin for constraint metrics.
+ * Constraint metrics can regress by at most this amount.
+ */
+export declare const DEFAULT_ALLOWED_MARGIN = 0.05;
+/**
+ * Minimum shadow window duration in milliseconds.
+ * A checkpoint must remain in shadow_ready for at least this duration
+ * before it can be promoted to promotable.
+ *
+ * Phase 7 default: 1 hour (3600000 ms)
+ * This gives time for real-world feedback before full promotion.
+ */
+export declare const MIN_SHADOW_WINDOW_MS: number;
+/**
+ * Promotion states for a checkpoint.
+ */
+export type PromotionState = 'rejected' | 'candidate_only' | 'shadow_ready' | 'promotable';
+/**
+ * Constraint metrics for promotion gate.
+ */
+export interface PromotionConstraints {
+    arbiterRejectRate: number;
+    executabilityRejectRate: number;
+    reviewedSubsetQuality: number;
+    routingScopeNotExpanded: boolean;
+}
+/**
+ * Baseline metrics for comparison.
+ */
+export interface BaselineMetrics {
+    arbiterRejectRate: number;
+    executabilityRejectRate: number;
+    reviewedSubsetQuality: number;
+}
+/**
+ * A promotion record — tracks the state and lineage of a promoted checkpoint.
+ */
+export interface PromotionRecord {
+    /** Unique identifier for this promotion record */
+    promotionId: string;
+    /** Checkpoint being promoted */
+    checkpointId: string;
+    /** Current promotion state */
+    state: PromotionState;
+    /** Worker profile this promotion targets */
+    targetProfile: TrainableWorkerProfile;
+    /** Target model family */
+    targetModelFamily: string;
+    /** Reduced-prompt holdout delta (primary objective) */
+    reducedPromptDelta: number;
+    /** Constraint metrics at time of promotion */
+    constraintMetrics: PromotionConstraints;
+    /** Baseline metrics used for comparison */
+    baselineMetrics: BaselineMetrics;
+    /** Whether orchestrator review was passed */
+    orchestratorReviewPassed: boolean;
+    /** Human review note (if any) */
+    reviewNote?: string;
+    /** ISO-8601 timestamp when state last changed */
+    stateChangedAt: string;
+    /** ISO-8601 timestamp when promotion record was created */
+    createdAt: string;
+    /** ISO-8601 timestamp when shadow window opened (if applicable) */
+    shadowStartedAt?: string;
+    /** ISO-8601 timestamp when promotable was achieved */
+    promotableAt?: string;
+    /** Previous promotion record ID (for rollback chain) */
+    previousPromotionId?: string;
+}
+/**
+ * The complete promotion registry.
+ */
+export interface PromotionRegistry {
+    promotions: PromotionRecord[];
+}
+/**
+ * Result of evaluating the promotion gate.
+ */
+export interface PromotionGateResult {
+    /** Whether the checkpoint passes the gate */
+    passes: boolean;
+    /** The promotion state if passed */
+    suggestedState?: PromotionState;
+    /** Reasons for rejection (if not passed) */
+    blockers: string[];
+    /** Details about each constraint check */
+    constraintChecks: {
+        constraint: string;
+        actual: number;
+        baseline: number;
+        threshold: number;
+        passed: boolean;
+        /** Source of the evidence: 'shadow' (real runtime) or 'eval-proxy' (fallback) */
+        source?: 'shadow' | 'eval-proxy';
+    }[];
+    /** Primary objective (delta) check */
+    deltaCheck: {
+        actual: number;
+        threshold: number;
+        passed: boolean;
+    };
+    evidenceSummary: {
+        evidenceMode: 'shadow' | 'eval-proxy' | 'mixed';
+        shadowSampleCount: number;
+        deltaSource: 'eval';
+    };
+}
+/**
+ * Parameters for evaluating the promotion gate.
+ */
+export interface EvaluateGateParams {
+    /** Checkpoint ID to evaluate */
+    checkpointId: string;
+    /** Target worker profile */
+    targetProfile: TrainableWorkerProfile;
+    /** Baseline metrics for comparison */
+    baselineMetrics: BaselineMetrics;
+    /** Minimum delta threshold for positive signal */
+    minDelta?: number;
+    /** Allowed margin for constraint metrics */
+    allowedMargin?: number;
+}
+/**
+ * Evaluate whether a checkpoint passes the promotion gate.
+ *
+ * @param stateDir - Workspace state directory
+ * @param params - Evaluation parameters
+ * @returns PromotionGateResult with pass/fail and details
+ *
+ * FAIL-CLOSED: Returns { passes: false } if:
+ *   - No eval attached to checkpoint
+ *   - Delta is negative or below threshold
+ *   - Any constraint metric regresses beyond allowed margin
+ *   - Profile is not in allowed rollout list
+ */
+export declare function evaluatePromotionGate(stateDir: string, params: EvaluateGateParams): PromotionGateResult;
+/**
+ * Parameters for advancing promotion state.
+ */
+export interface AdvancePromotionParams {
+    /** Checkpoint ID to promote */
+    checkpointId: string;
+    /** Target worker profile */
+    targetProfile: TrainableWorkerProfile;
+    /** Baseline metrics for comparison */
+    baselineMetrics: BaselineMetrics;
+    /** Orchestrator review passed (required for promotable) */
+    orchestratorReviewPassed?: boolean;
+    /** Human review note */
+    reviewNote?: string;
+    /** Minimum delta threshold */
+    minDelta?: number;
+    /** Allowed margin for constraints */
+    allowedMargin?: number;
+}
+/**
+ * Advance a checkpoint's promotion state.
+ *
+ * @param stateDir - Workspace state directory
+ * @param params - Advancement parameters
+ * @returns The updated PromotionRecord
+ *
+ * @throws Error if gate evaluation fails
+ * @throws Error if state transition is not allowed
+ */
+export declare function advancePromotion(stateDir: string, params: AdvancePromotionParams): PromotionRecord;
+/**
+ * Get the current promotion state for a checkpoint.
+ */
+export declare function getPromotionState(stateDir: string, checkpointId: string): PromotionState | null;
+/**
+ * Get the promotion record for a checkpoint.
+ */
+export declare function getPromotionRecord(stateDir: string, checkpointId: string): PromotionRecord | null;
+/**
+ * List promotions by state.
+ */
+export declare function listPromotionsByState(stateDir: string, state: PromotionState): PromotionRecord[];
+/**
+ * List all promotions for a profile.
+ */
+export declare function listPromotionsForProfile(stateDir: string, targetProfile: TrainableWorkerProfile): PromotionRecord[];
+/**
+ * Reject a checkpoint, preventing it from being promoted.
+ *
+ * @param stateDir - Workspace state directory
+ * @param checkpointId - Checkpoint to reject
+ * @param reason - Reason for rejection
+ * @returns The updated PromotionRecord
+ */
+export declare function rejectCheckpoint(stateDir: string, checkpointId: string, reason: string): PromotionRecord;
+/**
+ * Default baseline metrics for Phase 7.
+ * These represent the "acceptable" thresholds that new checkpoints must meet.
+ */
+export declare const DEFAULT_BASELINE_METRICS: BaselineMetrics;