zouroboros-selfheal 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 marlandoj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli/evolve.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+/**
+ * CLI for Zouroboros evolve — execute prescriptions with regression detection
+ *
+ * Usage: zouroboros-evolve [--prescription <path>] [--dry-run] [--skip-governor]
+ */
+export {};

package/dist/cli/evolve.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env bun
+/**
+ * CLI for Zouroboros evolve — execute prescriptions with regression detection
+ *
+ * Usage: zouroboros-evolve [--prescription <path>] [--dry-run] [--skip-governor]
+ */
+import { parseArgs } from 'util';
+import { evolve } from '../index.js';
+const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+        prescription: { type: 'string', short: 'p' },
+        'dry-run': { type: 'boolean' },
+        'skip-governor': { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+    },
+    strict: false,
+});
+if (values.help) {
+    console.log(`
+zouroboros-evolve — execute prescriptions with regression detection
+
+USAGE:
+  zouroboros-evolve [options]
+
+OPTIONS:
+  --prescription, -p   Path to prescription JSON (default: run prescribe first)
+  --dry-run            Show what would be executed without making changes
+  --skip-governor      Bypass the governor safety gate (use with caution)
+  --help, -h           Show this help
+
+SAFETY:
+  The governor gate blocks prescriptions with high regression risk.
+  Use --skip-governor only for manual overrides after review.
+  All evolutions are git-committed for rollback capability.
+
+EXAMPLES:
+  zouroboros-evolve --prescription ./prescription.json
+  zouroboros-evolve --dry-run
+  zouroboros-evolve --prescription ./rx.json --skip-governor
+`);
+    process.exit(0);
+}
+async function main() {
+    const result = await evolve({
+        prescription: values.prescription,
+        dryRun: !!values['dry-run'],
+        skipGovernor: !!values['skip-governor'],
+    });
+    if (result.success) {
+        console.log(`✓ Evolution complete`);
+        console.log(`  Delta:    ${(result.delta * 100).toFixed(1)}%`);
+        console.log(`  Reverted: ${result.reverted ? 'yes' : 'no'}`);
+        console.log(`  Detail:   ${result.detail}`);
+    }
+    else {
+        console.error(`✗ Evolution failed: ${result.detail}`);
+        process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error('Evolve failed:', err.message);
+    process.exit(1);
+});

package/dist/cli/introspect.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+/**
+ * CLI for Zouroboros introspection — 7-metric health scorecard
+ *
+ * Usage: zouroboros-introspect [--json] [--store] [--verbose]
+ */
+export {};

package/dist/cli/introspect.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env bun
+/**
+ * CLI for Zouroboros introspection — 7-metric health scorecard
+ *
+ * Usage: zouroboros-introspect [--json] [--store] [--verbose]
+ */
+import { parseArgs } from 'util';
+import { introspect } from '../index.js';
+import { formatScorecard } from '../introspect/scorecard.js';
+const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+        json: { type: 'boolean', short: 'j' },
+        store: { type: 'boolean', short: 's' },
+        verbose: { type: 'boolean', short: 'v' },
+        help: { type: 'boolean', short: 'h' },
+    },
+    strict: false,
+});
+if (values.help) {
+    console.log(`
+zouroboros-introspect — 7-metric health scorecard for Zo ecosystem
+
+USAGE:
+  zouroboros-introspect [options]
+
+OPTIONS:
+  --json, -j      Output raw JSON scorecard
+  --store, -s     Persist scorecard to ~/.zo/selfheal/
+  --verbose, -v   Print formatted scorecard table
+  --help, -h      Show this help
+
+METRICS:
+  memory_health     WAL size, episode count, decay distribution
+  skill_coverage    Skills with SKILL.md, scripts, references
+  eval_density      Evaluations per seed in last 30 days
+  swarm_success     Swarm procedure pass rate
+  persona_depth     Persona completeness (SOUL, rules, memory)
+  graph_connectivity  Cross-entity link density in knowledge graph
+  self_heal_cadence   Days since last introspect→prescribe→evolve cycle
+
+EXAMPLES:
+  zouroboros-introspect --verbose
+  zouroboros-introspect --json --store
+`);
+    process.exit(0);
+}
+async function main() {
+    const scorecard = await introspect({
+        json: !!values.json,
+        store: !!values.store,
+        verbose: !!values.verbose,
+    });
+    if (!values.json && !values.verbose) {
+        console.log(formatScorecard(scorecard));
+    }
+}
+main().catch((err) => {
+    console.error('Introspect failed:', err.message);
+    process.exit(1);
+});

package/dist/cli/prescribe.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+/**
+ * CLI for Zouroboros prescribe — auto-generate improvement seeds
+ *
+ * Usage: zouroboros-prescribe [--scorecard <path>] [--target <metric>] [--live] [--output <dir>] [--dry-run]
+ */
+export {};

package/dist/cli/prescribe.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env bun
+/**
+ * CLI for Zouroboros prescribe — auto-generate improvement seeds
+ *
+ * Usage: zouroboros-prescribe [--scorecard <path>] [--target <metric>] [--live] [--output <dir>] [--dry-run]
+ */
+import { parseArgs } from 'util';
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { prescribe } from '../index.js';
+const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+        scorecard: { type: 'string', short: 's' },
+        target: { type: 'string', short: 't' },
+        live: { type: 'boolean', short: 'l' },
+        output: { type: 'string', short: 'o', default: '.' },
+        'dry-run': { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+    },
+    strict: false,
+});
+if (values.help) {
+    console.log(`
+zouroboros-prescribe — generate improvement prescriptions from scorecard
+
+USAGE:
+  zouroboros-prescribe [options]
+
+OPTIONS:
+  --scorecard, -s  Path to a saved scorecard JSON (default: run live introspect)
+  --target, -t     Target metric name (default: weakest metric)
+  --live, -l       Run live introspection instead of using cached scorecard
+  --output, -o     Output directory for prescription (default: .)
+  --dry-run        Show what would be prescribed without writing files
+  --help, -h       Show this help
+
+PLAYBOOKS:
+  14 playbooks map metrics to concrete improvement strategies.
+  The governor gate evaluates risk before approving execution.
+
+EXAMPLES:
+  zouroboros-prescribe --live --target memory_health
+  zouroboros-prescribe --scorecard ./scorecard.json --output ./prescriptions
+  zouroboros-prescribe --dry-run
+`);
+    process.exit(0);
+}
+async function main() {
+    const prescription = await prescribe({
+        scorecard: values.scorecard,
+        live: !!values.live,
+        target: values.target,
+    });
+    if (values['dry-run']) {
+        console.log('\n[dry-run] Prescription:');
+        console.log(JSON.stringify(prescription, null, 2));
+        return;
+    }
+    const outDir = values.output || '.';
+    mkdirSync(outDir, { recursive: true });
+    const outPath = join(outDir, `prescription-${Date.now()}.json`);
+    writeFileSync(outPath, JSON.stringify(prescription, null, 2));
+    console.log(`✓ Prescription written to: ${outPath}`);
+    console.log(`  Metric:   ${prescription.metric.name} (${(prescription.metric.score * 100).toFixed(0)}%)`);
+    console.log(`  Playbook: ${prescription.playbook.name}`);
+    console.log(`  Governor: ${prescription.governor.approved ? 'APPROVED' : 'BLOCKED'}`);
+}
+main().catch((err) => {
+    console.error('Prescribe failed:', err.message);
+    process.exit(1);
+});

package/dist/evolve/executor.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Evolution executor for prescribed improvements
+ */
+import type { Prescription, EvolutionResult } from '../types.js';
+export declare function executeEvolution(prescription: Prescription, options: {
+    dryRun?: boolean;
+    skipGovernor?: boolean;
+}): Promise<EvolutionResult>;

package/dist/evolve/executor.js

@@ -0,0 +1,133 @@
+/**
+ * Evolution executor for prescribed improvements
+ */
+import { execSync } from 'child_process';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+const WORKSPACE = process.env.ZO_WORKSPACE || '/home/workspace';
+const RESULTS_DIR = join(WORKSPACE, 'Seeds/zouroboros/results');
+function run(cmd, timeout = 120000) {
+    try {
+        const stdout = execSync(cmd, {
+            cwd: WORKSPACE,
+            timeout,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return { stdout: stdout.trim(), ok: true, code: 0 };
+    }
+    catch (e) {
+        return { stdout: (e.stdout || '').toString().trim(), ok: false, code: e.status ?? 1 };
+    }
+}
+function measureMetric(cmd) {
+    const result = run(cmd, 60000);
+    if (!result.ok)
+        return null;
+    const num = parseFloat(result.stdout);
+    return isNaN(num) ? null : num;
+}
+async function executeAutoloopMode(prescription) {
+    const programPath = `/tmp/z-prescription-${prescription.id}.md`;
+    if (prescription.program) {
+        writeFileSync(programPath, prescription.program);
+    }
+    console.error(`  [evolve] Starting autoloop: ${prescription.playbook.name}`);
+    const result = run(`bun Skills/autoloop/scripts/autoloop.ts --program "${programPath}" 2>&1`, 8 * 60 * 60 * 1000 // 8 hour timeout
+    );
+    const success = result.ok && result.stdout.includes('KEEP');
+    return {
+        prescriptionId: prescription.id,
+        success,
+        baseline: { composite: prescription.metric.score, metrics: [] },
+        postFlight: null, // Would need to parse autoloop results
+        delta: 0,
+        reverted: !success,
+        detail: result.stdout.slice(0, 500),
+    };
+}
+async function executeScriptMode(prescription) {
+    console.error(`  [evolve] Executing script mode: ${prescription.playbook.name}`);
+    // Run setup commands
+    if (prescription.playbook.setupCommands) {
+        for (const cmd of prescription.playbook.setupCommands) {
+            console.error(`  [evolve] Setup: ${cmd.slice(0, 60)}...`);
+            const setupResult = run(cmd);
+            if (!setupResult.ok) {
+                return {
+                    prescriptionId: prescription.id,
+                    success: false,
+                    baseline: { composite: prescription.metric.score, metrics: [] },
+                    postFlight: null,
+                    delta: 0,
+                    reverted: false,
+                    detail: `Setup failed: ${setupResult.stdout.slice(0, 200)}`,
+                };
+            }
+        }
+    }
+    // Run main command
+    const runCmd = prescription.playbook.runCommand || 'echo "No run command"';
+    console.error(`  [evolve] Executing: ${runCmd.slice(0, 60)}...`);
+    const result = run(runCmd, 300000);
+    // Measure post-flight metric
+    const postValue = measureMetric(prescription.playbook.metricCommand);
+    const baseline = prescription.metric.value;
+    const delta = postValue !== null ? postValue - baseline : 0;
+    const improved = prescription.playbook.metricDirection === 'higher_is_better'
+        ? delta > 0
+        : delta < 0;
+    return {
+        prescriptionId: prescription.id,
+        success: result.ok,
+        baseline: { composite: baseline, metrics: [{ name: prescription.metric.name, value: baseline, score: prescription.metric.score, status: prescription.metric.status }] },
+        postFlight: postValue !== null ? {
+            composite: postValue,
+            metrics: [{ name: prescription.metric.name, value: postValue, score: postValue, status: improved ? 'HEALTHY' : prescription.metric.status }],
+        } : null,
+        delta,
+        reverted: !improved && result.ok,
+        detail: result.stdout.slice(0, 500),
+    };
+}
+export async function executeEvolution(prescription, options) {
+    const { dryRun = false, skipGovernor = false } = options;
+    // Governor check
+    if (!skipGovernor && !prescription.governor.approved) {
+        return {
+            prescriptionId: prescription.id,
+            success: false,
+            baseline: { composite: prescription.metric.score, metrics: [] },
+            postFlight: null,
+            delta: 0,
+            reverted: false,
+            detail: `Governor blocked: ${prescription.governor.reason}`,
+        };
+    }
+    if (dryRun) {
+        return {
+            prescriptionId: prescription.id,
+            success: true,
+            baseline: { composite: prescription.metric.score, metrics: [] },
+            postFlight: null,
+            delta: 0,
+            reverted: false,
+            detail: 'Dry run - no changes made',
+        };
+    }
+    // Ensure results directory
+    mkdirSync(RESULTS_DIR, { recursive: true });
+    // Execute based on mode
+    const result = prescription.program
+        ? await executeAutoloopMode(prescription)
+        : await executeScriptMode(prescription);
+    // Save result
+    const resultPath = join(RESULTS_DIR, `${prescription.id}-result.json`);
+    writeFileSync(resultPath, JSON.stringify(result, null, 2));
+    console.error(`  [evolve] Result: ${result.success ? '✅ SUCCESS' : '❌ FAILED'}`);
+    if (result.delta !== 0) {
+        const sign = result.delta > 0 ? '+' : '';
+        console.error(`  [evolve] Delta: ${sign}${(result.delta * 100).toFixed(1)}%`);
+    }
+    return result;
+}

package/dist/feedback.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Feedback Loop Tuning
+ *
+ * Auto-adjusts metric weights based on evolution outcomes.
+ * Learns which metrics are most predictive of successful improvements.
+ */
+import type { EvolutionResult, MetricResult } from './types.js';
+export interface WeightConfig {
+    weights: Record<string, number>;
+    learningRate: number;
+    minWeight: number;
+    maxWeight: number;
+    version: number;
+    lastUpdated: string;
+}
+export interface FeedbackRecord {
+    timestamp: string;
+    metricName: string;
+    prescriptionId: string;
+    baselineScore: number;
+    postFlightScore: number | null;
+    delta: number;
+    success: boolean;
+    weightBefore: number;
+    weightAfter: number;
+}
+export declare class FeedbackTuner {
+    private weightsFile;
+    private storeFile;
+    private config;
+    private store;
+    constructor(dataDir: string);
+    get weights(): Record<string, number>;
+    get version(): number;
+    recordOutcome(metric: MetricResult, result: EvolutionResult): FeedbackRecord;
+    getWeightForMetric(name: string): number;
+    getHistory(limit?: number): FeedbackRecord[];
+    getWeightHistory(limit?: number): Array<{
+        timestamp: string;
+        weights: Record<string, number>;
+        trigger: string;
+    }>;
+    getSuccessRate(metricName?: string): number;
+    getAvgDelta(metricName?: string): number;
+    resetWeights(): void;
+    private normalizeWeights;
+    private loadWeights;
+    private loadStore;
+    private save;
+}
+export declare function createFeedbackTuner(dataDir: string): FeedbackTuner;

package/dist/feedback.js

@@ -0,0 +1,160 @@
+/**
+ * Feedback Loop Tuning
+ *
+ * Auto-adjusts metric weights based on evolution outcomes.
+ * Learns which metrics are most predictive of successful improvements.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+const DEFAULT_WEIGHTS = {
+    'Memory Recall': 0.20,
+    'Graph Connectivity': 0.15,
+    'Routing Accuracy': 0.20,
+    'Eval Calibration': 0.15,
+    'Procedure Freshness': 0.15,
+    'Episode Velocity': 0.15,
+};
+export class FeedbackTuner {
+    weightsFile;
+    storeFile;
+    config;
+    store;
+    constructor(dataDir) {
+        mkdirSync(dataDir, { recursive: true });
+        this.weightsFile = join(dataDir, 'metric-weights.json');
+        this.storeFile = join(dataDir, 'feedback-store.json');
+        this.config = this.loadWeights();
+        this.store = this.loadStore();
+    }
+    get weights() {
+        return { ...this.config.weights };
+    }
+    get version() {
+        return this.config.version;
+    }
+    recordOutcome(metric, result) {
+        const weightBefore = this.config.weights[metric.name] || 0.10;
+        let weightAfter = weightBefore;
+        if (result.success && result.delta !== 0) {
+            // Successful evolution — adjust weight based on impact
+            const impactMagnitude = Math.abs(result.delta);
+            if (result.delta > 0) {
+                // Positive improvement — slightly increase weight (reward productive metrics)
+                weightAfter = weightBefore + this.config.learningRate * impactMagnitude;
+            }
+            else {
+                // Regression despite "success" — decrease weight
+                weightAfter = weightBefore - this.config.learningRate * impactMagnitude;
+            }
+        }
+        else if (!result.success) {
+            // Failed evolution — slightly decrease weight (this metric led to bad outcomes)
+            weightAfter = weightBefore - this.config.learningRate * 0.5;
+        }
+        // Clamp
+        weightAfter = Math.max(this.config.minWeight, Math.min(this.config.maxWeight, weightAfter));
+        const record = {
+            timestamp: new Date().toISOString(),
+            metricName: metric.name,
+            prescriptionId: result.prescriptionId,
+            baselineScore: metric.score,
+            postFlightScore: result.postFlight?.composite ?? null,
+            delta: result.delta,
+            success: result.success,
+            weightBefore,
+            weightAfter,
+        };
+        // Apply weight change
+        this.config.weights[metric.name] = weightAfter;
+        this.normalizeWeights();
+        this.config.version++;
+        this.config.lastUpdated = record.timestamp;
+        // Store record
+        this.store.records.push(record);
+        if (this.store.records.length > 500) {
+            this.store.records = this.store.records.slice(-500);
+        }
+        // Store weight snapshot
+        this.store.weightHistory.push({
+            timestamp: record.timestamp,
+            weights: { ...this.config.weights },
+            trigger: `${metric.name}: ${result.success ? 'success' : 'fail'} (delta=${result.delta.toFixed(4)})`,
+        });
+        if (this.store.weightHistory.length > 100) {
+            this.store.weightHistory = this.store.weightHistory.slice(-100);
+        }
+        this.save();
+        return record;
+    }
+    getWeightForMetric(name) {
+        return this.config.weights[name] || 0.10;
+    }
+    getHistory(limit = 20) {
+        return this.store.records.slice(-limit);
+    }
+    getWeightHistory(limit = 20) {
+        return this.store.weightHistory.slice(-limit);
+    }
+    getSuccessRate(metricName) {
+        const records = metricName
+            ? this.store.records.filter(r => r.metricName === metricName)
+            : this.store.records;
+        if (records.length === 0)
+            return 0;
+        return records.filter(r => r.success).length / records.length;
+    }
+    getAvgDelta(metricName) {
+        const records = metricName
+            ? this.store.records.filter(r => r.metricName === metricName)
+            : this.store.records;
+        if (records.length === 0)
+            return 0;
+        return records.reduce((sum, r) => sum + r.delta, 0) / records.length;
+    }
+    resetWeights() {
+        this.config.weights = { ...DEFAULT_WEIGHTS };
+        this.config.version++;
+        this.config.lastUpdated = new Date().toISOString();
+        this.save();
+    }
+    normalizeWeights() {
+        const total = Object.values(this.config.weights).reduce((s, w) => s + w, 0);
+        if (total === 0)
+            return;
+        for (const key of Object.keys(this.config.weights)) {
+            this.config.weights[key] /= total;
+        }
+    }
+    loadWeights() {
+        if (existsSync(this.weightsFile)) {
+            try {
+                return JSON.parse(readFileSync(this.weightsFile, 'utf-8'));
+            }
+            catch { /* fall through */ }
+        }
+        return {
+            weights: { ...DEFAULT_WEIGHTS },
+            learningRate: 0.05,
+            minWeight: 0.05,
+            maxWeight: 0.40,
+            version: 0,
+            lastUpdated: new Date().toISOString(),
+        };
+    }
+    loadStore() {
+        if (existsSync(this.storeFile)) {
+            try {
+                return JSON.parse(readFileSync(this.storeFile, 'utf-8'));
+            }
+            catch { /* fall through */ }
+        }
+        return { records: [], weightHistory: [] };
+    }
+    save() {
+        writeFileSync(this.weightsFile, JSON.stringify(this.config, null, 2));
+        writeFileSync(this.storeFile, JSON.stringify(this.store, null, 2));
+    }
+}
+export function createFeedbackTuner(dataDir) {
+    return new FeedbackTuner(dataDir);
+}

package/dist/history.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Evolution History
+ *
+ * Track and visualize system improvements over time.
+ */
+import type { EvolutionResult, ScorecardSnapshot } from './types.js';
+export interface HistoryEntry {
+    id: string;
+    timestamp: string;
+    prescriptionId: string;
+    playbookId: string;
+    playbookName: string;
+    metricName: string;
+    baseline: ScorecardSnapshot;
+    postFlight: ScorecardSnapshot | null;
+    delta: number;
+    success: boolean;
+    reverted: boolean;
+    duration?: number;
+    tags: string[];
+}
+export interface HistoryStats {
+    totalEvolutions: number;
+    successCount: number;
+    failCount: number;
+    revertCount: number;
+    successRate: number;
+    avgDelta: number;
+    avgPositiveDelta: number;
+    bestEvolution: HistoryEntry | null;
+    worstEvolution: HistoryEntry | null;
+    streakCurrent: number;
+    streakBest: number;
+    byMetric: Record<string, {
+        count: number;
+        avgDelta: number;
+        successRate: number;
+    }>;
+    byPlaybook: Record<string, {
+        count: number;
+        avgDelta: number;
+        successRate: number;
+    }>;
+}
+export interface TrendPoint {
+    timestamp: string;
+    composite: number;
+    metrics: Record<string, number>;
+}
+export declare class EvolutionHistory {
+    private dataFile;
+    private store;
+    private maxEntries;
+    private maxTrends;
+    constructor(dataDir: string, maxEntries?: number, maxTrends?: number);
+    record(entry: Omit<HistoryEntry, 'id'>): HistoryEntry;
+    recordFromResult(result: EvolutionResult, playbookId: string, playbookName: string, metricName: string, tags?: string[]): HistoryEntry;
+    getStats(): HistoryStats;
+    getTrends(limit?: number): TrendPoint[];
+    getEntries(options?: {
+        limit?: number;
+        metricName?: string;
+        playbookId?: string;
+        successOnly?: boolean;
+    }): HistoryEntry[];
+    getRecentEntries(limit?: number): HistoryEntry[];
+    clear(): void;
+    private load;
+    private save;
+}
+export declare function createEvolutionHistory(dataDir: string): EvolutionHistory;