zouroboros-workflow 2.0.0

package/dist/evaluate/mechanical.js

@@ -0,0 +1,106 @@
+/**
+ * Stage 1: Mechanical verification
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+/**
+ * Run mechanical checks on an artifact
+ */
+export function runMechanicalChecks(artifactPath) {
+    const checks = [];
+    const hasPackageJson = existsSync(join(artifactPath, 'package.json'));
+    const hasTsConfig = existsSync(join(artifactPath, 'tsconfig.json'));
+    const hasPyFiles = hasPythonFiles(artifactPath);
+    // TypeScript checks
+    if (hasTsConfig) {
+        checks.push(checkTypeScript(artifactPath));
+    }
+    // Lint check
+    if (hasPackageJson) {
+        checks.push(checkLint(artifactPath));
+        checks.push(checkTests(artifactPath));
+    }
+    // Python checks
+    if (hasPyFiles) {
+        checks.push(checkPythonSyntax(artifactPath));
+    }
+    return checks.filter(Boolean);
+}
+function checkTypeScript(artifactPath) {
+    try {
+        execSync(`cd "${artifactPath}" && npx tsc --noEmit 2>&1`, {
+            encoding: 'utf-8',
+            timeout: 30000,
+        });
+        return { name: 'TypeScript compile', passed: true, detail: 'No type errors' };
+    }
+    catch (e) {
+        const output = e.stdout || e.message || 'Unknown error';
+        const errorLines = output.split('\n').filter((l) => l.includes('error TS')).slice(0, 5);
+        return {
+            name: 'TypeScript compile',
+            passed: false,
+            detail: errorLines.join('; ') || 'Compilation failed',
+        };
+    }
+}
+function checkLint(artifactPath) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(artifactPath, 'package.json'), 'utf-8'));
+        if (!pkg.scripts?.lint) {
+            return { name: 'Lint', passed: true, detail: 'No lint script configured' };
+        }
+        execSync(`cd "${artifactPath}" && npm run lint 2>&1`, {
+            encoding: 'utf-8',
+            timeout: 30000,
+        });
+        return { name: 'Lint', passed: true, detail: 'No lint errors' };
+    }
+    catch (e) {
+        const output = (e.stdout || '').split('\n').slice(-5).join('; ');
+        return { name: 'Lint', passed: false, detail: output || 'Lint failed' };
+    }
+}
+function checkTests(artifactPath) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(artifactPath, 'package.json'), 'utf-8'));
+        if (!pkg.scripts?.test) {
+            return { name: 'Tests', passed: true, detail: 'No test script configured' };
+        }
+        const result = execSync(`cd "${artifactPath}" && npm test 2>&1`, {
+            encoding: 'utf-8',
+            timeout: 60000,
+        });
+        const passMatch = result.match(/(\d+)\s*(?:tests?\s*)?pass/i);
+        return {
+            name: 'Tests',
+            passed: true,
+            detail: passMatch ? `${passMatch[1]} passing` : 'All tests passed',
+        };
+    }
+    catch (e) {
+        const output = (e.stdout || '').split('\n').slice(-5).join('; ');
+        return { name: 'Tests', passed: false, detail: output || 'Tests failed' };
+    }
+}
+function checkPythonSyntax(artifactPath) {
+    try {
+        execSync(`cd "${artifactPath}" && python3 -m py_compile $(find . -name "*.py" -maxdepth 3 | head -10 | tr '\\n' ' ') 2>&1`, { encoding: 'utf-8', timeout: 15000 });
+        return { name: 'Python syntax', passed: true, detail: 'No syntax errors' };
+    }
+    catch (e) {
+        return { name: 'Python syntax', passed: false, detail: 'Syntax errors found' };
+    }
+}
+function hasPythonFiles(artifactPath) {
+    try {
+        const result = execSync(`find "${artifactPath}" -name "*.py" -maxdepth 3 | head -1`, {
+            encoding: 'utf-8',
+        });
+        return result.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/evaluate/semantic.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Stage 2: Semantic evaluation
+ */
+import type { SeedSpec, SemanticResult } from './types.js';
+/**
+ * Parse a seed specification from YAML content
+ */
+export declare function parseSeed(seedPath: string): SeedSpec;
+/**
+ * Run semantic evaluation against acceptance criteria
+ */
+export declare function runSemanticEvaluation(seed: SeedSpec, artifactPath: string): SemanticResult;
+export declare function calculateDrift(seed: SeedSpec, artifactPath: string): number;

package/dist/evaluate/semantic.js

@@ -0,0 +1,167 @@
+/**
+ * Stage 2: Semantic evaluation
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+/**
+ * Parse a seed specification from YAML content
+ */
+export function parseSeed(seedPath) {
+    const content = readFileSync(seedPath, 'utf-8');
+    const spec = {};
+    const goalMatch = content.match(/^goal:\s*"?(.+?)"?\s*$/m);
+    if (goalMatch)
+        spec.goal = goalMatch[1];
+    spec.constraints = [];
+    spec.acceptanceCriteria = [];
+    const lines = content.split('\n');
+    let inConstraints = false;
+    let inAC = false;
+    for (const line of lines) {
+        if (line.match(/^constraints:/)) {
+            inConstraints = true;
+            inAC = false;
+            continue;
+        }
+        if (line.match(/^acceptance_criteria:/)) {
+            inAC = true;
+            inConstraints = false;
+            continue;
+        }
+        if (line.match(/^[a-z_]+:/) && !line.startsWith('  ')) {
+            inConstraints = false;
+            inAC = false;
+            continue;
+        }
+        const itemMatch = line.match(/^\s+-\s+"?(.+?)"?\s*$/);
+        if (itemMatch) {
+            if (inConstraints)
+                spec.constraints.push(itemMatch[1]);
+            if (inAC)
+                spec.acceptanceCriteria.push(itemMatch[1]);
+        }
+    }
+    return spec;
+}
+/**
+ * Run semantic evaluation against acceptance criteria
+ */
+export function runSemanticEvaluation(seed, artifactPath) {
+    const criteria = [];
+    for (const ac of seed.acceptanceCriteria || []) {
+        const evidence = searchForEvidence(ac, artifactPath);
+        criteria.push({
+            name: ac,
+            met: evidence.found,
+            evidence: evidence.details,
+        });
+    }
+    const metCount = criteria.filter((c) => c.met).length;
+    const totalCount = criteria.length || 1;
+    const acCompliance = metCount / totalCount;
+    // Calculate goal alignment (simplified)
+    const goalAlignment = calculateGoalAlignment(seed, artifactPath);
+    // Calculate drift score
+    const driftScore = calculateDrift(seed, artifactPath);
+    // Overall score
+    const overallScore = 0.5 * goalAlignment + 0.3 * acCompliance + 0.2 * (1 - driftScore);
+    const recommendations = [];
+    if (acCompliance < 0.8) {
+        const unmet = criteria.filter(c => !c.met).map(c => c.name);
+        recommendations.push(`Unmet acceptance criteria: ${unmet.join(', ')}`);
+    }
+    if (goalAlignment < 0.7) {
+        recommendations.push('Goal alignment is low — verify implementation matches the stated objective');
+    }
+    if (driftScore > 0.3) {
+        recommendations.push('Significant drift detected — review scope changes against original spec');
+    }
+    return {
+        acCompliance,
+        goalAlignment,
+        driftScore,
+        overallScore,
+        criteria,
+        recommendations,
+        passed: overallScore >= 0.8,
+    };
+}
+function searchForEvidence(criterion, artifactPath) {
+    const keywords = criterion.toLowerCase().split(/\s+/).filter((w) => w.length > 3);
+    let foundCount = 0;
+    let searchedFiles = 0;
+    function searchDir(dir, depth = 0) {
+        if (depth > 3)
+            return;
+        try {
+            const entries = readdirSync(dir);
+            for (const entry of entries) {
+                if (entry.startsWith('.') || entry === 'node_modules')
+                    continue;
+                const fullPath = join(dir, entry);
+                const stat = statSync(fullPath);
+                if (stat.isDirectory()) {
+                    searchDir(fullPath, depth + 1);
+                }
+                else if (stat.isFile() && isCodeFile(entry)) {
+                    searchedFiles++;
+                    try {
+                        const content = readFileSync(fullPath, 'utf-8').toLowerCase();
+                        const matches = keywords.filter((kw) => content.includes(kw)).length;
+                        if (matches >= Math.ceil(keywords.length / 2)) {
+                            foundCount++;
+                        }
+                    }
+                    catch {
+                        // Skip unreadable files
+                    }
+                }
+            }
+        }
+        catch {
+            // Skip inaccessible directories
+        }
+    }
+    if (existsSync(artifactPath)) {
+        const stat = statSync(artifactPath);
+        if (stat.isDirectory()) {
+            searchDir(artifactPath);
+        }
+        else if (stat.isFile()) {
+            searchedFiles = 1;
+            try {
+                const content = readFileSync(artifactPath, 'utf-8').toLowerCase();
+                const matches = keywords.filter((kw) => content.includes(kw)).length;
+                if (matches >= Math.ceil(keywords.length / 2)) {
+                    foundCount++;
+                }
+            }
+            catch {
+                // Skip
+            }
+        }
+    }
+    return {
+        found: foundCount > 0,
+        details: searchedFiles > 0
+            ? `Found evidence in ${foundCount} of ${searchedFiles} searched files`
+            : 'No files searched',
+    };
+}
+function isCodeFile(filename) {
+    const codeExts = ['.ts', '.js', '.tsx', '.jsx', '.py', '.go', '.rs', '.java', '.cpp', '.c', '.h', '.md'];
+    return codeExts.some((ext) => filename.endsWith(ext));
+}
+function calculateGoalAlignment(seed, artifactPath) {
+    // Simplified goal alignment check
+    if (!seed.goal)
+        return 0.5;
+    const goalKeywords = seed.goal.toLowerCase().split(/\s+/).filter((w) => w.length > 4);
+    const evidence = searchForEvidence(seed.goal, artifactPath);
+    return evidence.found ? 0.9 : 0.5;
+}
+export function calculateDrift(seed, artifactPath) {
+    // Simplified drift calculation
+    // In a full implementation, this would compare ontology fields, constraints, etc.
+    return 0.1; // Assume low drift for now
+}

package/dist/evaluate/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Types for three-stage evaluation
+ */
+export interface MechanicalCheck {
+    name: string;
+    passed: boolean;
+    detail: string;
+}
+export interface SemanticCriterion {
+    name: string;
+    met: boolean;
+    evidence: string;
+}
+export interface SemanticResult {
+    acCompliance: number;
+    goalAlignment: number;
+    driftScore: number;
+    overallScore: number;
+    criteria: SemanticCriterion[];
+    recommendations: string[];
+    passed: boolean;
+}
+export interface ConsensusVote {
+    perspective: 'proposer' | 'devils_advocate' | 'synthesizer';
+    verdict: 'approve' | 'reject';
+    reasoning: string;
+}
+export interface ConsensusResult {
+    votes: ConsensusVote[];
+    finalVerdict: 'approve' | 'reject';
+    confidence: number;
+}
+export interface EvaluationReport {
+    id: string;
+    seedId: string;
+    artifactPath: string;
+    timestamp: string;
+    stage1: {
+        passed: boolean;
+        checks: MechanicalCheck[];
+    };
+    stage2: SemanticResult | null;
+    stage3: ConsensusResult | null;
+    decision: 'approved' | 'needs_work' | 'rejected';
+    recommendations: string[];
+}
+export interface SeedSpec {
+    id?: string;
+    goal?: string;
+    constraints?: string[];
+    acceptanceCriteria?: string[];
+    evaluationPrinciples?: Array<{
+        name: string;
+        description: string;
+        weight: number;
+    }>;
+}

package/dist/evaluate/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for three-stage evaluation
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Zouroboros Workflow
+ *
+ * Spec-first development tools: interview, evaluation, unstuck, and autoloop.
+ *
+ * @module zouroboros-workflow
+ */
+export { scoreAmbiguity, } from './interview/ambiguity.js';
+export { generateSeed, formatSeedYAML, } from './interview/seed.js';
+export type { InterviewConfig, AmbiguityScore, SeedSpecification } from './interview/types.js';
+export { runMechanicalChecks } from './evaluate/mechanical.js';
+export { parseSeed, runSemanticEvaluation, calculateDrift } from './evaluate/semantic.js';
+export type { MechanicalCheck, SeedSpec, SemanticResult, EvaluationReport } from './evaluate/types.js';
+export { autoSelectPersona, getStrategy, getAllPersonas, STRATEGIES } from './unstuck/strategies.js';
+export type { UnstuckPersona, UnstuckStrategy, UnstuckSession, AutoSelectResult } from './unstuck/types.js';
+export { parseProgram, validateProgram } from './autoloop/parser.js';
+export { initState, shouldContinue, isBetter, runExperiment, saveResults, getStagnationLevel, getStagnationModifier } from './autoloop/loop.js';
+export type { ProgramConfig, MetricConfig, ConstraintConfig, StagnationConfig, ExperimentRecord, LoopState, LoopStatus } from './autoloop/types.js';
+export declare const VERSION = "2.0.0";

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * Zouroboros Workflow
+ *
+ * Spec-first development tools: interview, evaluation, unstuck, and autoloop.
+ *
+ * @module zouroboros-workflow
+ */
+// Spec-First Interview
+export { scoreAmbiguity, } from './interview/ambiguity.js';
+export { generateSeed, formatSeedYAML, } from './interview/seed.js';
+// Three-Stage Evaluation
+export { runMechanicalChecks } from './evaluate/mechanical.js';
+export { parseSeed, runSemanticEvaluation, calculateDrift } from './evaluate/semantic.js';
+// Unstuck Lateral
+export { autoSelectPersona, getStrategy, getAllPersonas, STRATEGIES } from './unstuck/strategies.js';
+// Autoloop
+export { parseProgram, validateProgram } from './autoloop/parser.js';
+export { initState, shouldContinue, isBetter, runExperiment, saveResults, getStagnationLevel, getStagnationModifier } from './autoloop/loop.js';
+// Version
+export const VERSION = '2.0.0';

package/dist/interview/ambiguity.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Ambiguity scoring for spec-first interview
+ */
+import type { AmbiguityScore } from './types.js';
+/**
+ * Score the ambiguity of a request
+ * Returns goal clarity, constraint clarity, success criteria clarity, and overall ambiguity
+ */
+export declare function scoreAmbiguity(request: string): AmbiguityScore;

package/dist/interview/ambiguity.js

@@ -0,0 +1,53 @@
+/**
+ * Ambiguity scoring for spec-first interview
+ */
+/**
+ * Score the ambiguity of a request
+ * Returns goal clarity, constraint clarity, success criteria clarity, and overall ambiguity
+ */
+export function scoreAmbiguity(request) {
+    let goal = 0;
+    let constraints = 0;
+    let success = 0;
+    const words = request.toLowerCase().split(/\s+/);
+    const len = words.length;
+    // Goal clarity signals
+    const goalSignals = ['build', 'create', 'implement', 'add', 'fix', 'migrate', 'refactor', 'deploy', 'integrate'];
+    const hasVerb = goalSignals.some((s) => words.includes(s));
+    const hasObject = len > 2;
+    const hasSpecificity = len > 6;
+    goal = (hasVerb ? 0.3 : 0) + (hasObject ? 0.3 : 0.1) + (hasSpecificity ? 0.4 : 0.1);
+    // Constraint signals
+    const constraintWords = ['must', 'should', 'only', 'without', 'using', 'in', 'with', 'no', 'cannot', 'limit'];
+    const constraintCount = constraintWords.filter((w) => words.includes(w)).length;
+    constraints = Math.min(1.0, constraintCount * 0.25);
+    // Success criteria signals
+    const successWords = ['when', 'so that', 'passes', 'returns', 'displays', 'sends', 'saves', 'validates'];
+    const successCount = successWords.filter((w) => request.toLowerCase().includes(w)).length;
+    success = Math.min(1.0, successCount * 0.3);
+    // Vagueness penalties
+    const vagueWords = ['better', 'faster', 'improve', 'optimize', 'fix', 'update', 'change', 'nice', 'good'];
+    const vagueCount = vagueWords.filter((w) => words.includes(w)).length;
+    const vaguePenalty = vagueCount * 0.15;
+    goal = Math.max(0, Math.min(1, goal - vaguePenalty * 0.5));
+    constraints = Math.max(0, Math.min(1, constraints));
+    success = Math.max(0, Math.min(1, success));
+    const ambiguity = +(1 - (goal * 0.4 + constraints * 0.3 + success * 0.3)).toFixed(2);
+    let assessment;
+    if (ambiguity <= 0.2) {
+        assessment = 'READY — Ambiguity is low enough to proceed to seed generation.';
+    }
+    else if (ambiguity <= 0.5) {
+        assessment = 'NEEDS CLARIFICATION — Run a Socratic interview to fill gaps.';
+    }
+    else {
+        assessment = 'HIGH AMBIGUITY — Significant interview required before any implementation.';
+    }
+    return {
+        goal: +goal.toFixed(2),
+        constraints: +constraints.toFixed(2),
+        success: +success.toFixed(2),
+        ambiguity,
+        assessment,
+    };
+}

package/dist/interview/seed.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Seed specification generator
+ */
+import type { SeedSpecification } from './types.js';
+/**
+ * Generate a seed specification from interview notes
+ */
+export declare function generateSeed(topic: string, notesPath?: string, interviewNotes?: string): SeedSpecification;
+/**
+ * Format seed as YAML string
+ */
+export declare function formatSeedYAML(seed: SeedSpecification): string;

package/dist/interview/seed.js

@@ -0,0 +1,120 @@
+/**
+ * Seed specification generator
+ */
+import { randomUUID } from 'crypto';
+import { existsSync, readFileSync } from 'fs';
+/**
+ * Generate a seed specification from interview notes
+ */
+export function generateSeed(topic, notesPath, interviewNotes) {
+    const id = `seed-${randomUUID().slice(0, 8)}`;
+    const now = new Date().toISOString();
+    let notes = interviewNotes || '';
+    if (notesPath && existsSync(notesPath)) {
+        notes = readFileSync(notesPath, 'utf-8');
+    }
+    // Extract information from notes if available
+    const constraints = extractConstraints(notes);
+    const acceptanceCriteria = extractAcceptanceCriteria(notes);
+    return {
+        id,
+        created: now,
+        status: 'draft',
+        goal: topic || 'TODO: Define the primary objective',
+        constraints: constraints.length > 0 ? constraints : ['TODO: Add hard constraints from interview'],
+        acceptanceCriteria: acceptanceCriteria.length > 0
+            ? acceptanceCriteria
+            : ['TODO: Add measurable success criteria'],
+        ontology: {
+            name: 'TODO',
+            description: 'TODO: Describe the domain model',
+            fields: [
+                { name: 'id', type: 'string', description: 'Unique identifier' },
+            ],
+        },
+        evaluationPrinciples: [
+            { name: 'correctness', description: 'Does it do what was asked?', weight: 0.4 },
+            { name: 'completeness', description: 'Are all acceptance criteria met?', weight: 0.3 },
+            { name: 'quality', description: 'Is the implementation sound?', weight: 0.3 },
+        ],
+        exitConditions: [
+            { name: 'all_ac_met', description: 'All acceptance criteria satisfied', criteria: 'AC compliance = 100%' },
+        ],
+    };
+}
+/**
+ * Format seed as YAML string
+ */
+export function formatSeedYAML(seed) {
+    const fieldsYAML = seed.ontology.fields
+        .map(f => `    - name: ${f.name}\n      type: ${f.type}\n      description: "${f.description}"`)
+        .join('\n');
+    const principlesYAML = seed.evaluationPrinciples
+        .map(p => `  - name: ${p.name}\n    description: "${p.description}"\n    weight: ${p.weight}`)
+        .join('\n');
+    const exitYAML = seed.exitConditions
+        .map(e => `  - name: ${e.name}\n    description: "${e.description}"\n    criteria: "${e.criteria}"`)
+        .join('\n');
+    return `# Seed Specification
+# Generated: ${seed.created}
+# ID: ${seed.id}
+
+id: "${seed.id}"
+created: "${seed.created}"
+status: ${seed.status}
+
+goal: "${seed.goal}"
+
+constraints:
+${seed.constraints.map(c => `  - "${c}"`).join('\n')}
+
+acceptance_criteria:
+${seed.acceptanceCriteria.map(ac => `  - "${ac}"`).join('\n')}
+
+ontology:
+  name: "${seed.ontology.name}"
+  description: "${seed.ontology.description}"
+  fields:
+${fieldsYAML}
+
+evaluation_principles:
+${principlesYAML}
+
+exit_conditions:
+${exitYAML}
+`;
+}
+function extractConstraints(notes) {
+    const constraints = [];
+    const lines = notes.split('\n');
+    let inConstraints = false;
+    for (const line of lines) {
+        if (line.match(/constraint|must|should|limit|restriction/i)) {
+            inConstraints = true;
+        }
+        if (inConstraints && line.trim().startsWith('-')) {
+            constraints.push(line.replace(/^-\s*/, '').trim());
+        }
+        if (line.match(/acceptance|criteria|success/i)) {
+            inConstraints = false;
+        }
+    }
+    return constraints;
+}
+function extractAcceptanceCriteria(notes) {
+    const criteria = [];
+    const lines = notes.split('\n');
+    let inCriteria = false;
+    for (const line of lines) {
+        if (line.match(/acceptance|criteria|success|should.*when/i)) {
+            inCriteria = true;
+        }
+        if (inCriteria && line.trim().startsWith('-')) {
+            criteria.push(line.replace(/^-\s*/, '').trim());
+        }
+        if (line.match(/evaluation|exit|complete/i)) {
+            inCriteria = false;
+        }
+    }
+    return criteria;
+}

package/dist/interview/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Types for spec-first interview
+ */
+export interface InterviewConfig {
+    topic: string;
+    outputDir: string;
+    maxQuestions?: number;
+}
+export interface AmbiguityScore {
+    goal: number;
+    constraints: number;
+    success: number;
+    ambiguity: number;
+    assessment: string;
+}
+export interface SeedSpecification {
+    id: string;
+    created: string;
+    status: 'draft' | 'approved' | 'rejected';
+    goal: string;
+    constraints: string[];
+    acceptanceCriteria: string[];
+    ontology: {
+        name: string;
+        description: string;
+        fields: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+    };
+    evaluationPrinciples: Array<{
+        name: string;
+        description: string;
+        weight: number;
+    }>;
+    exitConditions: Array<{
+        name: string;
+        description: string;
+        criteria: string;
+    }>;
+}
+export interface InterviewSession {
+    id: string;
+    topic: string;
+    questions: string[];
+    answers: string[];
+    timestamp: number;
+}

package/dist/interview/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for spec-first interview
+ */
+export {};

package/dist/unstuck/strategies.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Unstuck persona strategies and auto-selection
+ */
+import type { UnstuckPersona, UnstuckStrategy, AutoSelectResult } from './types.js';
+/**
+ * All available unstuck strategies
+ */
+export declare const STRATEGIES: Record<UnstuckPersona, UnstuckStrategy>;
+/**
+ * Auto-select the best unstuck persona based on problem description
+ */
+export declare function autoSelectPersona(problem: string): AutoSelectResult;
+/**
+ * Get strategy for a specific persona
+ */
+export declare function getStrategy(persona: UnstuckPersona): UnstuckStrategy;
+/**
+ * Get all available personas
+ */
+export declare function getAllPersonas(): UnstuckPersona[];