principles-disciple 1.7.6 → 1.7.8

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

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

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

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