principles-disciple 1.8.1 → 1.8.2

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

@@ -1,85 +0,0 @@
-/**
- * Nocturnal Executability Checker — Bounded Action Validation
- * =========================================================
- *
- * PURPOSE: Validate that a reflection artifact's suggestions are actually
- * executable — i.e., they describe bounded, concrete actions rather than
- * vague platitudes or impossible feats.
- *
- * EXECUTABILITY CRITERIA:
- * 1. next-step is a bounded action (not a vague improvement)
- * 2. No references to non-existent tools
- * 3. No references to impossible/implied actions
- * 4. The suggestion can be translated into a tool call
- *
- * DESIGN CONSTRAINTS:
- * - Pure functions only — no I/O, no side effects
- * - Deterministic — same input always produces same output
- * - Fail closed — non-executable suggestions are rejected
- * - No LLM involvement — all checks are algorithmic
- */
-/**
- * A bounded action that could be translated to a tool call.
- */
-export interface BoundedAction {
-    /** The action verb (e.g., 'read', 'edit', 'check') */
-    verb: string;
-    /** The target of the action (e.g., 'src/main.ts', 'documentation') */
-    target: string;
-    /** The full suggestion text */
-    fullText: string;
-}
-/**
- * Executability validation failure.
- */
-export interface ExecutabilityFailure {
-    reason: string;
-    field: 'badDecision' | 'betterDecision';
-}
-/**
- * Result of executability validation.
- */
-export interface ExecutabilityResult {
-    /** Whether the suggestion passed executability checks */
-    executable: boolean;
-    /** Parsed bounded action from betterDecision (if executable) */
-    boundedAction?: BoundedAction;
-    /** Failure reasons (if not executable) */
-    failures: ExecutabilityFailure[];
-}
-/**
- * Validate that a reflection artifact's suggestions are executable.
- *
- * @param artifact - The validated artifact from arbiter (passed = true)
- * @returns ExecutabilityResult
- */
-export declare function validateExecutability(artifact: {
-    badDecision: string;
-    betterDecision: string;
-}): ExecutabilityResult;
-/**
- * Combined arbiter + executability check.
- *
- * @param rawJson - Raw JSON string from reflector
- * @param options - Expected values for cross-validation
- * @returns Combined result with all failure reasons
- */
-export interface CombinedValidationResult {
-    approved: boolean;
-    artifact?: {
-        artifactId: string;
-        sessionId: string;
-        principleId: string;
-        sourceSnapshotRef: string;
-        badDecision: string;
-        betterDecision: string;
-        rationale: string;
-        createdAt: string;
-        boundedAction?: BoundedAction;
-    };
-    failures: string[];
-}
-export declare function validateForApproval(rawJson: string, options?: {
-    expectedPrincipleId?: string;
-    expectedSessionId?: string;
-}): CombinedValidationResult;

package/dist/core/nocturnal-executability.js

@@ -1,331 +0,0 @@
-/**
- * Nocturnal Executability Checker — Bounded Action Validation
- * =========================================================
- *
- * PURPOSE: Validate that a reflection artifact's suggestions are actually
- * executable — i.e., they describe bounded, concrete actions rather than
- * vague platitudes or impossible feats.
- *
- * EXECUTABILITY CRITERIA:
- * 1. next-step is a bounded action (not a vague improvement)
- * 2. No references to non-existent tools
- * 3. No references to impossible/implied actions
- * 4. The suggestion can be translated into a tool call
- *
- * DESIGN CONSTRAINTS:
- * - Pure functions only — no I/O, no side effects
- * - Deterministic — same input always produces same output
- * - Fail closed — non-executable suggestions are rejected
- * - No LLM involvement — all checks are algorithmic
- */
-import { parseAndValidateArtifact } from './nocturnal-arbiter.js';
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-/**
- * Known tool verbs that map to bounded actions.
- * These are the only verbs that can be translated to tool calls.
- */
-const BOUNDED_TOOL_VERBS = new Set([
-    'read',
-    'edit',
-    'write',
-    'create',
-    'delete',
-    'check',
-    'verify',
-    'test',
-    'run',
-    'execute',
-    'install',
-    'search',
-    'grep',
-    'find',
-    'list',
-    'review',
-    'examine',
-    'inspect',
-    'look',
-    'view',
-    'open',
-    'close',
-    'save',
-    'commit',
-    'push',
-    'pull',
-    'fetch',
-    'merge',
-    'diff',
-    'analyze',
-    'diagnose',
-    'debug',
-    'trace',
-]);
-/**
- * Vague verbs that cannot be translated to bounded tool calls.
- */
-const VAGUE_VERBS = new Set([
-    'understand',
-    'learn',
-    'improve',
-    'better',
-    'fix',
-    'handle',
-    'manage',
-    'work',
-    'do',
-    'make',
-    'get',
-    'got',
-    'ensure',
-    'ensure that',
-    'be',
-    'consider',
-    'think',
-    'reflect',
-    'analyze',
-    'evaluate',
-    'review', // borderline - sometimes acceptable
-    'help',
-    'support',
-    'provide',
-    'offer',
-    'give',
-    'take',
-    'use',
-    'try',
-    'attempt',
-    'start',
-    'begin',
-    'continue',
-    'proceed',
-    'finish',
-    'complete',
-    'end',
-    'stop',
-    'avoid',
-    'prevent',
-    'reduce',
-    'minimize',
-    'maximize',
-    'optimize',
-    'enhance',
-    'strengthen',
-    'develop',
-    'grow',
-    'build',
-    'establish',
-    'create', // borderline - sometimes acceptable
-    'implement',
-    'deploy',
-    'launch',
-]);
-/**
- * Patterns that indicate vague/hollow格言 (not a decision-point).
- */
-const HOLLOW_PATTERNS = [
-    /always be careful/i,
-    /always be mindful/i,
-    /always think before acting/i,
-    /don't rush/i,
-    /take your time/i,
-    /be patient/i,
-    /be careful/i,
-    /be more careful/i,
-    /be mindful/i,
-    /work smarter/i,
-    /be more effective/i,
-    /be better/i,
-    /good practice/i,
-    /best practice/i,
-    /should be careful/i,
-    /need to be more/i,
-    /should have been more/i,
-];
-// ---------------------------------------------------------------------------
-// Parsing
-// ---------------------------------------------------------------------------
-/**
- * Attempt to parse a suggestion into a bounded action.
- *
- * Looks for patterns like:
- * - "Read X before doing Y"
- * - "Check X first"
- * - "Verify Y"
- * - "Edit X to do Z"
- */
-function parseBoundedAction(text) {
-    const trimmed = text.trim();
-    const lower = trimmed.toLowerCase();
-    // Pattern: "Read/Check/Verify X" or "X. Read/Check/Verify Y"
-    const boundedPattern = /^([A-Za-z]+)\s+(?:the\s+)?([^\s.,]+(?:\s+[^\s.,]+){0,5})/i;
-    const match = trimmed.match(boundedPattern);
-    if (match) {
-        const verb = match[1].toLowerCase();
-        const target = match[2].trim();
-        if (BOUNDED_TOOL_VERBS.has(verb) && target.length > 0) {
-            return { verb, target, fullText: trimmed };
-        }
-    }
-    // Pattern: "[Verb] the [target]" — e.g., "read the file"
-    const thePattern = /^(read|check|verify|edit|write|delete|search|grep|look|examine|inspect|review)\s+(?:the\s+)?(.+)/i;
-    const theMatch = lower.match(thePattern);
-    if (theMatch) {
-        return { verb: theMatch[1], target: theMatch[2].trim(), fullText: trimmed };
-    }
-    return null;
-}
-// ---------------------------------------------------------------------------
-// Core Validation
-// ---------------------------------------------------------------------------
-/**
- * Check if a text contains a hollow格言 pattern.
- */
-function containsHollowPattern(text) {
-    return HOLLOW_PATTERNS.some((p) => p.test(text));
-}
-/**
- * Check if a text contains vague verbs that cannot be executed.
- */
-function containsVagueVerb(text) {
-    const lower = text.toLowerCase();
-    // Check if the text STARTS with a vague verb (most indicative of non-executable)
-    for (const vagueVerb of VAGUE_VERBS) {
-        if (lower.startsWith(vagueVerb + ' ') || lower.startsWith(vagueVerb + 's ')) {
-            return true;
-        }
-    }
-    return false;
-}
-/**
- * Check if a text is too generic to be actionable.
- */
-function isTooGeneric(text) {
-    const lower = text.toLowerCase();
-    // Very short suggestions are often too generic
-    if (text.trim().length < 15)
-        return true;
-    // Check for generic patterns
-    if (/^[^,]*,?\s*(not|never|no\b|don't|don't|shouldn't|cannot|can't)/i.test(lower)) {
-        // This is actually a negative constraint, not an action
-        return true;
-    }
-    if (/\bthen\b/i.test(lower) && lower.split(/\bthen\b/i).length > 4) {
-        // Multi-step vague instruction (5 or more "then" words)
-        return true;
-    }
-    return false;
-}
-// ---------------------------------------------------------------------------
-// Main Validator
-// ---------------------------------------------------------------------------
-/**
- * Validate that a reflection artifact's suggestions are executable.
- *
- * @param artifact - The validated artifact from arbiter (passed = true)
- * @returns ExecutabilityResult
- */
-export function validateExecutability(artifact) {
-    const failures = [];
-    // Check badDecision is not hollow
-    if (containsHollowPattern(artifact.badDecision)) {
-        failures.push({
-            reason: 'badDecision contains a hollow principle statement, not a decision-point',
-            field: 'badDecision',
-        });
-    }
-    // Check betterDecision is executable
-    const boundedAction = parseBoundedAction(artifact.betterDecision);
-    const lowerBetter = artifact.betterDecision.toLowerCase();
-    // Check 1: Not a hollow pattern
-    if (containsHollowPattern(artifact.betterDecision)) {
-        failures.push({
-            reason: 'betterDecision contains a hollow principle statement, not an actionable decision',
-            field: 'betterDecision',
-        });
-    }
-    // Check 2: Does not start with vague verb
-    if (containsVagueVerb(artifact.betterDecision)) {
-        failures.push({
-            reason: 'betterDecision starts with a vague verb that cannot be translated to a tool call',
-            field: 'betterDecision',
-        });
-    }
-    // Check 3: Not too generic
-    if (isTooGeneric(artifact.betterDecision)) {
-        failures.push({
-            reason: 'betterDecision is too generic to be an actionable decision-point',
-            field: 'betterDecision',
-        });
-    }
-    // Check 4: Contains a parseable bounded action
-    if (boundedAction === null && failures.length === 0) {
-        failures.push({
-            reason: 'betterDecision does not describe a bounded action that can be translated to a tool call',
-            field: 'betterDecision',
-        });
-    }
-    // Check 5: Does not reference non-existent operations
-    // (This is a heuristic — we can't know all tool names, but we can flag obvious non-tools)
-    const nonToolReferences = [
-        /rewrite the entire/i,
-        /redesign the whole/i,
-        /restart from scratch/i,
-        /rebuild from zero/i,
-        /change the fundamental/i,
-    ];
-    for (const pattern of nonToolReferences) {
-        if (pattern.test(artifact.betterDecision)) {
-            failures.push({
-                reason: 'betterDecision references an operation that is too broad to be a bounded action',
-                field: 'betterDecision',
-            });
-            break;
-        }
-    }
-    // Check 6: badDecision should describe a specific failure, not a generic anti-pattern
-    const genericBadPatterns = [
-        /did not \w+ properly/i,
-        /failed to \w+ correctly/i,
-        /made a mistake/i,
-        /was wrong/i,
-        /was incorrect/i,
-    ];
-    for (const pattern of genericBadPatterns) {
-        if (pattern.test(artifact.badDecision) && !pattern.test(artifact.betterDecision)) {
-            // This is OK — badDecision can be generic, it's the betterDecision that must be specific
-        }
-    }
-    if (failures.length > 0) {
-        return { executable: false, failures };
-    }
-    return {
-        executable: true,
-        boundedAction: boundedAction ?? undefined,
-        failures: [],
-    };
-}
-export function validateForApproval(rawJson, options = {}) {
-    const arbiterResult = parseAndValidateArtifact(rawJson, options);
-    if (!arbiterResult.passed || !arbiterResult.artifact) {
-        return {
-            approved: false,
-            failures: arbiterResult.failures.map((f) => f.reason),
-        };
-    }
-    const execResult = validateExecutability(arbiterResult.artifact);
-    if (!execResult.executable) {
-        return {
-            approved: false,
-            failures: execResult.failures.map((f) => f.reason),
-        };
-    }
-    return {
-        approved: true,
-        artifact: {
-            ...arbiterResult.artifact,
-            boundedAction: execResult.boundedAction,
-        },
-        failures: [],
-    };
-}

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

@@ -1,124 +0,0 @@
-/**
- * Nocturnal ORPO Export — Approved Dataset to Decision-Point JSONL
- * =================================================================
- *
- * PURPOSE: Export approved nocturnal samples as ORPO-formatted decision-point
- * training JSONL, strictly separated from legacy correction export.
- *
- * ARCHITECTURE:
- *   - Export output: .state/exports/orpo/{exportId}.jsonl
- *   - Export manifest: .state/exports/orpo/{exportId}-manifest.json
- *   - Legacy corrections: untouched, separate path
- *
- * ORPO FORMAT (each line):
- *   {
- *     sampleFingerprint: string,
- *     artifactId: string,
- *     sessionId: string,
- *     principleId: string,
- *     targetModelFamily: string,
- *     prompt: string,        // badDecision (the wrong choice)
- *     chosen: string,        // betterDecision (the right choice)
- *     rejected: string,       // badDecision (for ORPO)
- *     rationale: string,
- *     datasetMetadata: {
- *       sampleFingerprint: string,
- *       artifactPath: string,
- *       createdAt: string,
- *       exportedAt: string,
- *       exportId: string,
- *       datasetFingerprint: string
- *     }
- *   }
- *
- * EXPORT GATING (fail-closed):
- *   - reviewStatus === 'approved_for_training'
- *   - targetModelFamily matches requested target (or any if not specified)
- *   - Lineage fields complete (sampleFingerprint, artifactId, sessionId, principleId)
- *   - Source artifact file exists and is approved
- *
- * DESIGN CONSTRAINTS:
- *   - No trainer invocation
- *   - No automatic training
- *   - No checkpoint deploy
- *   - Export is read-only from dataset perspective
- */
-/**
- * A single ORPO training sample in JSONL format.
- */
-export interface ORPOSample {
-    sampleFingerprint: string;
-    artifactId: string;
-    sessionId: string;
-    principleId: string;
-    targetModelFamily: string;
-    /** The suboptimal decision (what the agent did wrong) */
-    prompt: string;
-    /** The correct decision (what should have been done) */
-    chosen: string;
-    /** The suboptimal decision (same as prompt, for ORPO structure) */
-    rejected: string;
-    rationale: string;
-    datasetMetadata: {
-        sampleFingerprint: string;
-        artifactPath: string;
-        createdAt: string;
-        exportedAt: string;
-        exportId: string;
-        datasetFingerprint: string;
-    };
-}
-/**
- * Export manifest containing metadata about the entire export.
- */
-export interface ORPOExportManifest {
-    exportId: string;
-    createdAt: string;
-    sampleCount: number;
-    targetModelFamily: string;
-    /** SHA-256 of all sample fingerprints, sorted — for reproducibility */
-    datasetFingerprint: string;
-    exportPath: string;
-    manifestPath: string;
-    samples: Array<{
-        sampleFingerprint: string;
-        artifactId: string;
-        sessionId: string;
-        principleId: string;
-    }>;
-}
-/**
- * Result of an export operation.
- */
-export interface ExportResult {
-    success: boolean;
-    manifest?: ORPOExportManifest;
-    error?: string;
-    emptyReason?: 'no_approved_samples' | 'family_mismatch' | 'all_samples_missing_artifacts';
-}
-/**
- * Export approved nocturnal samples as ORPO decision-point JSONL.
- *
- * @param workspaceDir - Workspace directory
- * @param targetModelFamily - Specific model family to export, or undefined for all
- * @param options - Additional export options
- * @returns ExportResult
- */
-export declare function exportORPOSamples(workspaceDir: string, targetModelFamily?: string | null, _options?: Record<string, never>): ExportResult;
-/**
- * Verify an existing export by re-computing its dataset fingerprint.
- * Returns true if the export is intact and reproducible.
- */
-export declare function verifyExportIntegrity(workspaceDir: string, exportId: string): {
-    valid: boolean;
-    computedFingerprint: string;
-    manifestFingerprint: string;
-} | null;
-/**
- * List all exports in the exports directory.
- */
-export declare function listExports(workspaceDir: string): ORPOExportManifest[];
-/**
- * Read an export manifest by ID.
- */
-export declare function getExportManifest(workspaceDir: string, exportId: string): ORPOExportManifest | null;