zouroboros-workflow 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/README.md

@@ -0,0 +1,153 @@
+# zouroboros-workflow
+
+> Spec-first development tools: interview, evaluation, unstuck, and autoloop
+
+## Features
+
+- **Spec-First Interview** — Socratic interview process to clarify requirements before building
+- **Three-Stage Evaluation** — Mechanical → Semantic → Consensus verification pipeline
+- **Unstuck Lateral** — 5 lateral-thinking personas for breaking through stagnation
+- **Autoloop** — Autonomous single-metric optimization with git-based improvement tracking
+
+## Installation
+
+```bash
+npm install zouroboros-workflow
+# or
+pnpm add zouroboros-workflow
+```
+
+## CLI Usage
+
+### Spec-First Interview
+
+```bash
+# Score ambiguity of a request
+zouroboros-interview score --request "Make the site faster"
+
+# Generate seed specification
+zouroboros-interview seed --topic "Build a webhook retry system"
+
+# Interactive interview guide
+zouroboros-interview --topic "Your topic here"
+```
+
+### Three-Stage Evaluation
+
+```bash
+# Run full evaluation pipeline
+zouroboros-evaluate --seed seed.yaml --artifact ./src/
+
+# Run only mechanical checks
+zouroboros-evaluate --seed seed.yaml --artifact ./src/ --stage 1
+
+# Self-test current workspace
+zouroboros-evaluate --self-test
+```
+
+### Unstuck Lateral
+
+```bash
+# Auto-select persona based on problem
+zouroboros-unstuck --problem "The API keeps returning 403 errors"
+
+# Use specific persona
+zouroboros-unstuck --problem "This refactor touches 20 files" --persona architect
+
+# List all personas
+zouroboros-unstuck --list
+```
+
+### Autoloop
+
+```bash
+# Validate program configuration
+zouroboros-autoloop --program ./program.md --dry-run
+
+# Run optimization loop
+zouroboros-autoloop --program ./program.md
+
+# Resume from existing branch
+zouroboros-autoloop --program ./program.md --resume
+```
+
+## Programmatic API
+
+### Spec-First Interview
+
+```typescript
+import { scoreAmbiguity, generateSeedTemplate } from 'zouroboros-workflow';
+
+// Score ambiguity before building
+const score = scoreAmbiguity("Build a webhook retry system");
+console.log(score.ambiguity); // 0.35 (needs clarification)
+console.log(score.assessment); // "NEEDS CLARIFICATION"
+
+// Generate seed after interview
+const seed = generateSeedTemplate("Webhook Retry System", "./interview-notes.md");
+```
+
+### Three-Stage Evaluation
+
+```typescript
+import { parseSeed, runMechanicalChecks, evaluateSemantic } from 'zouroboros-workflow';
+
+// Parse seed specification
+const seed = parseSeed('./seed.yaml');
+
+// Stage 1: Mechanical verification
+const checks = runMechanicalChecks('./src/');
+// [ { name: 'TypeScript compile', passed: true, detail: 'No errors' }, ... ]
+
+// Stage 2: Semantic evaluation
+const result = evaluateSemantic(seed, './src/');
+console.log(result.overallScore); // 0.85
+console.log(result.decision); // 'APPROVED' | 'NEEDS_WORK'
+```
+
+### Unstuck Lateral
+
+```typescript
+import { autoSelectPersona, getStrategy } from 'zouroboros-workflow';
+
+// Auto-select best persona
+const selection = autoSelectPersona("I'm stuck on this API error");
+console.log(selection.persona); // 'hacker'
+console.log(selection.confidence); // 0.85
+
+// Get strategy details
+const strategy = getStrategy('hacker');
+console.log(strategy.philosophy);
+console.log(strategy.approach);
+```
+
+### Autoloop
+
+```typescript
+import { parseProgram, initState, shouldContinue, runExperiment } from 'zouroboros-workflow';
+
+// Parse program configuration
+const config = parseProgram('./program.md');
+
+// Initialize loop
+const state = initState(config, 'autoloop/my-optimization');
+
+// Run loop
+while (shouldContinue(state, config).continue) {
+  // Propose change via AI executor
+  // Apply change to target file
+  // Git commit
+  
+  // Run experiment
+  const result = await runExperiment(config, './');
+  
+  // Decide keep or revert
+  if (result.metric !== null) {
+    // Update state, commit or revert
+  }
+}
+```
+
+## License
+
+MIT

package/dist/autoloop/loop.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Core autoloop optimization engine
+ */
+import type { ProgramConfig, LoopState, ExperimentRecord } from './types.js';
+/**
+ * Initialize the loop state
+ */
+export declare function initState(config: ProgramConfig, branch: string): LoopState;
+/**
+ * Check if the loop should continue
+ */
+export declare function shouldContinue(state: LoopState, config: ProgramConfig): {
+    continue: boolean;
+    reason?: string;
+};
+/**
+ * Check if a metric is better than the current best
+ */
+export declare function isBetter(metric: number, best: number, direction: 'lower_is_better' | 'higher_is_better'): boolean;
+/**
+ * Extract metric from command output
+ */
+export declare function extractMetric(output: string, extractPattern: string): number | null;
+/**
+ * Run the experiment and extract metric
+ */
+export declare function runExperiment(config: ProgramConfig, workDir: string): Promise<{
+    metric: number | null;
+    output: string;
+    durationMs: number;
+    error?: string;
+}>;
+/**
+ * Format results as TSV
+ */
+export declare function formatResultsTSV(results: ExperimentRecord[]): string;
+/**
+ * Save loop results to file
+ */
+export declare function saveResults(state: LoopState, config: ProgramConfig, outputPath: string): void;
+/**
+ * Calculate stagnation level
+ */
+export declare function getStagnationLevel(state: LoopState, config: ProgramConfig): 0 | 1 | 2 | 3;
+/**
+ * Get prompt modifier based on stagnation level
+ */
+export declare function getStagnationModifier(level: number): string;

package/dist/autoloop/loop.js

@@ -0,0 +1,145 @@
+/**
+ * Core autoloop optimization engine
+ */
+import { $ } from 'bun';
+import { writeFileSync } from 'fs';
+/**
+ * Initialize the loop state
+ */
+export function initState(config, branch) {
+    return {
+        bestMetric: config.metric.direction === 'lower_is_better' ? Infinity : -Infinity,
+        bestCommit: '',
+        experimentCount: 0,
+        stagnationCount: 0,
+        totalCostUSD: 0,
+        startTime: Date.now(),
+        results: [],
+        branch
+    };
+}
+/**
+ * Check if the loop should continue
+ */
+export function shouldContinue(state, config) {
+    // Check experiment limit
+    if (state.experimentCount >= config.constraints.maxExperiments) {
+        return { continue: false, reason: `Reached max experiments (${config.constraints.maxExperiments})` };
+    }
+    // Check duration limit
+    const elapsedHours = (Date.now() - state.startTime) / (1000 * 60 * 60);
+    if (elapsedHours >= config.constraints.maxDurationHours) {
+        return { continue: false, reason: `Reached max duration (${config.constraints.maxDurationHours}h)` };
+    }
+    // Check cost limit
+    if (state.totalCostUSD >= config.constraints.maxCostUSD) {
+        return { continue: false, reason: `Reached max cost ($${config.constraints.maxCostUSD})` };
+    }
+    return { continue: true };
+}
+/**
+ * Check if a metric is better than the current best
+ */
+export function isBetter(metric, best, direction) {
+    if (direction === 'lower_is_better') {
+        return metric < best;
+    }
+    return metric > best;
+}
+/**
+ * Extract metric from command output
+ */
+export function extractMetric(output, extractPattern) {
+    try {
+        // Try to parse as a number directly
+        const direct = parseFloat(output.trim());
+        if (!isNaN(direct))
+            return direct;
+        // Try regex pattern
+        const regex = new RegExp(extractPattern);
+        const match = output.match(regex);
+        if (match) {
+            const num = parseFloat(match[1] || match[0]);
+            if (!isNaN(num))
+                return num;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the experiment and extract metric
+ */
+export async function runExperiment(config, workDir) {
+    const startTime = Date.now();
+    try {
+        // Run the command with timeout
+        const shell = $ `cd ${workDir} && ${config.runCommand}`.nothrow();
+        const result = await shell.timeout(config.constraints.timeBudgetSeconds * 1000);
+        const durationMs = Date.now() - startTime;
+        const output = result.stdout.toString() + result.stderr.toString();
+        // Extract metric
+        const metric = extractMetric(output, config.metric.extract);
+        return {
+            metric,
+            output,
+            durationMs,
+            error: result.exitCode !== 0 ? `Exit code ${result.exitCode}` : undefined
+        };
+    }
+    catch (e) {
+        const durationMs = Date.now() - startTime;
+        return {
+            metric: null,
+            output: '',
+            durationMs,
+            error: e.message
+        };
+    }
+}
+/**
+ * Format results as TSV
+ */
+export function formatResultsTSV(results) {
+    const lines = ['commit\tmetric\tstatus\tdescription\ttimestamp\tduration_ms'];
+    for (const r of results) {
+        lines.push(`${r.commit}\t${r.metric}\t${r.status}\t"${r.description}"\t${r.timestamp}\t${r.durationMs}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Save loop results to file
+ */
+export function saveResults(state, config, outputPath) {
+    const tsv = formatResultsTSV(state.results);
+    writeFileSync(outputPath, tsv);
+}
+/**
+ * Calculate stagnation level
+ */
+export function getStagnationLevel(state, config) {
+    if (state.stagnationCount >= config.stagnation.tripleThreshold)
+        return 3;
+    if (state.stagnationCount >= config.stagnation.doubleThreshold)
+        return 2;
+    if (state.stagnationCount >= config.stagnation.threshold)
+        return 1;
+    return 0;
+}
+/**
+ * Get prompt modifier based on stagnation level
+ */
+export function getStagnationModifier(level) {
+    switch (level) {
+        case 1:
+            return '\n[Stagnation detected — try a more aggressive change or different approach]';
+        case 2:
+            return '\n[Significant stagnation — consider a completely different strategy]';
+        case 3:
+            return '\n[Critical stagnation — radical change required, explore very different solutions]';
+        default:
+            return '';
+    }
+}

package/dist/autoloop/parser.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parse program.md files for autoloop
+ */
+import type { ProgramConfig } from './types.js';
+/**
+ * Parse a program.md file into configuration
+ */
+export declare function parseProgram(path: string): ProgramConfig;
+/**
+ * Validate a program configuration
+ */
+export declare function validateProgram(config: ProgramConfig): string[];

package/dist/autoloop/parser.js

@@ -0,0 +1,121 @@
+/**
+ * Parse program.md files for autoloop
+ */
+import { readFileSync } from 'fs';
+/**
+ * Extract a section from markdown by heading
+ */
+function getSection(content, heading) {
+    const re = new RegExp(`^##\\s+${heading}\\s*$`, 'im');
+    const match = content.match(re);
+    if (!match || match.index === undefined)
+        return '';
+    const start = match.index + match[0].length;
+    const nextHeading = content.slice(start).search(/^##\s+/m);
+    const end = nextHeading === -1 ? content.length : start + nextHeading;
+    return content.slice(start, end).trim();
+}
+/**
+ * Extract a field from a section
+ */
+function getField(section, field) {
+    const re = new RegExp(`^-\\s+\\*\\*${field}\\*\\*:\\s*(.+)$`, 'im');
+    const match = section.match(re);
+    return match ? match[1].trim() : '';
+}
+/**
+ * Parse a number from constraint text
+ */
+function parseConstraint(content, label, fallback) {
+    const re = new RegExp(`\\*\\*${label}\\*\\*:\\s*([\\d.]+)`, 'i');
+    const m = content.match(re);
+    return m ? parseFloat(m[1]) : fallback;
+}
+/**
+ * Parse a stagnation threshold
+ */
+function parseStagnation(content, label, fallback) {
+    const re = new RegExp(`\\*\\*${label}\\*\\*:\\s*(\\d+)`, 'i');
+    const m = content.match(re);
+    return m ? parseInt(m[1]) : fallback;
+}
+/**
+ * Parse a program.md file into configuration
+ */
+export function parseProgram(path) {
+    const raw = readFileSync(path, 'utf-8');
+    // Extract name from title
+    const nameMatch = raw.match(/^#\s+Program:\s*(.+)$/m);
+    const name = nameMatch ? nameMatch[1].trim() : 'unnamed';
+    // Extract metric section
+    const metricSection = getSection(raw, 'Metric');
+    const metricName = getField(metricSection, 'name');
+    const direction = getField(metricSection, 'direction');
+    const extract = getField(metricSection, 'extract').replace(/^`|`$/g, '');
+    // Extract constraints
+    const constraintsSection = getSection(raw, 'Constraints');
+    // Extract stagnation config
+    const stagnationSection = getSection(raw, 'Stagnation');
+    // Extract read-only files
+    const readOnlySection = getSection(raw, 'Read-Only Files');
+    const readOnlyFiles = readOnlySection
+        .split('\n')
+        .map(l => l.replace(/^-\s*/, '').trim())
+        .filter(Boolean);
+    // Extract setup code
+    const setupSection = getSection(raw, 'Setup');
+    const setupMatch = setupSection.match(/```(?:bash)?\n([\s\S]*?)```/);
+    // Extract run command
+    const runSection = getSection(raw, 'Run Command');
+    const runMatch = runSection.match(/```(?:bash)?\n([\s\S]*?)```/);
+    // Extract target file
+    const targetSection = getSection(raw, 'Target File');
+    const targetFile = targetSection.split('\n')[0].replace(/^`|`$/g, '').trim();
+    return {
+        name,
+        objective: getSection(raw, 'Objective'),
+        metric: {
+            name: metricName,
+            direction: direction || 'lower_is_better',
+            extract
+        },
+        setup: setupMatch ? setupMatch[1].trim() : setupSection,
+        targetFile,
+        runCommand: runMatch ? runMatch[1].trim() : runSection.split('\n')[0],
+        readOnlyFiles,
+        constraints: {
+            timeBudgetSeconds: parseConstraint(constraintsSection, 'Time budget per run', 300),
+            maxExperiments: parseConstraint(constraintsSection, 'Max experiments', 100),
+            maxDurationHours: parseConstraint(constraintsSection, 'Max duration', 8),
+            maxCostUSD: parseConstraint(constraintsSection, 'Max cost', 10)
+        },
+        stagnation: {
+            threshold: parseStagnation(stagnationSection, 'Threshold', 10),
+            doubleThreshold: parseStagnation(stagnationSection, 'Double threshold', 20),
+            tripleThreshold: parseStagnation(stagnationSection, 'Triple threshold', 30)
+        },
+        notes: getSection(raw, 'Notes')
+    };
+}
+/**
+ * Validate a program configuration
+ */
+export function validateProgram(config) {
+    const errors = [];
+    if (!config.name || config.name === 'unnamed') {
+        errors.push('Program must have a name');
+    }
+    if (!config.metric.name) {
+        errors.push('Metric must have a name');
+    }
+    if (!config.metric.extract) {
+        errors.push('Metric must have an extract command/pattern');
+    }
+    if (!config.targetFile) {
+        errors.push('Target file must be specified');
+    }
+    if (!config.runCommand) {
+        errors.push('Run command must be specified');
+    }
+    return errors;
+}

package/dist/autoloop/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Types for autoloop optimization
+ */
+export interface MetricConfig {
+    name: string;
+    direction: 'lower_is_better' | 'higher_is_better';
+    extract: string;
+}
+export interface ConstraintConfig {
+    timeBudgetSeconds: number;
+    maxExperiments: number;
+    maxDurationHours: number;
+    maxCostUSD: number;
+}
+export interface StagnationConfig {
+    threshold: number;
+    doubleThreshold: number;
+    tripleThreshold: number;
+}
+export interface ProgramConfig {
+    name: string;
+    objective: string;
+    metric: MetricConfig;
+    setup: string;
+    targetFile: string;
+    runCommand: string;
+    readOnlyFiles: string[];
+    constraints: ConstraintConfig;
+    stagnation: StagnationConfig;
+    notes: string;
+}
+export interface ExperimentRecord {
+    commit: string;
+    metric: number;
+    status: 'keep' | 'discard' | 'crash';
+    description: string;
+    timestamp: string;
+    durationMs: number;
+}
+export interface LoopState {
+    bestMetric: number;
+    bestCommit: string;
+    experimentCount: number;
+    stagnationCount: number;
+    totalCostUSD: number;
+    startTime: number;
+    results: ExperimentRecord[];
+    branch: string;
+}
+export interface LoopStatus {
+    running: boolean;
+    state: LoopState | null;
+    config: ProgramConfig | null;
+}

package/dist/autoloop/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for autoloop optimization
+ */
+export {};

package/dist/cli/autoloop.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+/**
+ * CLI for autoloop optimization
+ *
+ * Usage: zouroboros-autoloop --program <program.md>
+ */
+export {};