elsabro 2.3.0 → 3.7.0

package/references/output-schemas.md

@@ -0,0 +1,858 @@
+---
+name: output-schemas
+description: Sistema de validación de outputs con schemas JSON/Zod
+version: 1.0.0
+---
+
+# ELSABRO Output Schemas System
+
+## Vision General
+
+El sistema de Output Schemas garantiza que los outputs de agentes cumplan con estructuras definidas, proporcionando type-safety y comunicación predecible entre componentes.
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                    OUTPUT VALIDATION FLOW                                 │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   AGENT OUTPUT                                                           │
+│       │                                                                  │
+│       ▼                                                                  │
+│   ┌──────────────┐                                                       │
+│   │    PARSE     │ ──── Extract structured data from response            │
+│   └──────┬───────┘                                                       │
+│          │                                                               │
+│          ▼                                                               │
+│   ┌──────────────┐     INVALID    ┌──────────────┐                      │
+│   │   VALIDATE   │ ─────────────► │    RETRY     │                      │
+│   │  (vs Schema) │                │ (with hints) │                      │
+│   └──────┬───────┘                └──────────────┘                      │
+│          │ VALID                                                         │
+│          ▼                                                               │
+│   ┌──────────────┐                                                       │
+│   │  TRANSFORM   │ ──── Apply defaults, coerce types                    │
+│   └──────┬───────┘                                                       │
+│          │                                                               │
+│          ▼                                                               │
+│   TYPED OUTPUT                                                           │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Definición de Schemas
+
+### JSON Schema Format
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "elsabro://schemas/analysis-result",
+  "title": "AnalysisResult",
+  "description": "Output schema for analysis agent",
+  "type": "object",
+  "required": ["summary", "files", "recommendations"],
+  "properties": {
+    "summary": {
+      "type": "string",
+      "description": "Brief summary of the analysis",
+      "minLength": 10,
+      "maxLength": 500
+    },
+    "files": {
+      "type": "array",
+      "description": "Files analyzed",
+      "items": {
+        "type": "object",
+        "required": ["path", "purpose"],
+        "properties": {
+          "path": { "type": "string" },
+          "purpose": { "type": "string" },
+          "complexity": {
+            "type": "string",
+            "enum": ["low", "medium", "high"]
+          },
+          "linesOfCode": { "type": "integer", "minimum": 0 }
+        }
+      }
+    },
+    "recommendations": {
+      "type": "array",
+      "description": "List of recommendations",
+      "items": {
+        "type": "object",
+        "required": ["action", "priority"],
+        "properties": {
+          "action": { "type": "string" },
+          "priority": {
+            "type": "string",
+            "enum": ["low", "medium", "high", "critical"]
+          },
+          "reason": { "type": "string" }
+        }
+      }
+    },
+    "techDebt": {
+      "type": "object",
+      "properties": {
+        "score": { "type": "number", "minimum": 0, "maximum": 10 },
+        "issues": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}
+```
+
+### TypeScript/Zod Format
+
+```typescript
+import { z } from 'zod';
+
+// Schema para resultado de análisis
+export const AnalysisResultSchema = z.object({
+  summary: z.string().min(10).max(500).describe('Brief summary of the analysis'),
+
+  files: z.array(z.object({
+    path: z.string(),
+    purpose: z.string(),
+    complexity: z.enum(['low', 'medium', 'high']).optional(),
+    linesOfCode: z.number().int().nonnegative().optional()
+  })).describe('Files analyzed'),
+
+  recommendations: z.array(z.object({
+    action: z.string(),
+    priority: z.enum(['low', 'medium', 'high', 'critical']),
+    reason: z.string().optional()
+  })).describe('List of recommendations'),
+
+  techDebt: z.object({
+    score: z.number().min(0).max(10),
+    issues: z.array(z.string())
+  }).optional()
+});
+
+export type AnalysisResult = z.infer<typeof AnalysisResultSchema>;
+
+// Schema para resultado de implementación
+export const ImplementationResultSchema = z.object({
+  success: z.boolean(),
+
+  filesCreated: z.array(z.object({
+    path: z.string(),
+    purpose: z.string(),
+    linesAdded: z.number().int().nonnegative()
+  })).default([]),
+
+  filesModified: z.array(z.object({
+    path: z.string(),
+    changes: z.string(),
+    linesAdded: z.number().int().nonnegative(),
+    linesRemoved: z.number().int().nonnegative()
+  })).default([]),
+
+  testsCreated: z.array(z.object({
+    path: z.string(),
+    testCount: z.number().int().positive(),
+    coverage: z.number().min(0).max(100).optional()
+  })).default([]),
+
+  decisions: z.array(z.object({
+    question: z.string(),
+    decision: z.string(),
+    reasoning: z.string(),
+    alternatives: z.array(z.string()).optional()
+  })).default([]),
+
+  errors: z.array(z.object({
+    type: z.string(),
+    message: z.string(),
+    file: z.string().optional(),
+    line: z.number().optional()
+  })).default([])
+});
+
+export type ImplementationResult = z.infer<typeof ImplementationResultSchema>;
+
+// Schema para resultado de review
+export const ReviewResultSchema = z.object({
+  approved: z.boolean(),
+
+  issues: z.array(z.object({
+    severity: z.enum(['critical', 'high', 'medium', 'low', 'info']),
+    type: z.enum(['bug', 'security', 'performance', 'style', 'maintainability']),
+    file: z.string(),
+    line: z.number().optional(),
+    message: z.string(),
+    suggestion: z.string().optional(),
+    autoFixable: z.boolean().default(false)
+  })).default([]),
+
+  summary: z.object({
+    critical: z.number().int().nonnegative(),
+    high: z.number().int().nonnegative(),
+    medium: z.number().int().nonnegative(),
+    low: z.number().int().nonnegative(),
+    info: z.number().int().nonnegative()
+  }),
+
+  recommendation: z.enum(['approve', 'request_changes', 'needs_discussion'])
+});
+
+export type ReviewResult = z.infer<typeof ReviewResultSchema>;
+```
+
+---
+
+## Schemas Predefinidos
+
+### 1. AnalysisResult
+
+Para agentes de análisis (elsabro-analyst, Explore, Plan).
+
+```javascript
+{
+  summary: string,
+  files: Array<{ path, purpose, complexity?, linesOfCode? }>,
+  recommendations: Array<{ action, priority, reason? }>,
+  techDebt?: { score, issues }
+}
+```
+
+### 2. ImplementationResult
+
+Para agentes de implementación (elsabro-executor, elsabro-quick-dev).
+
+```javascript
+{
+  success: boolean,
+  filesCreated: Array<{ path, purpose, linesAdded }>,
+  filesModified: Array<{ path, changes, linesAdded, linesRemoved }>,
+  testsCreated: Array<{ path, testCount, coverage? }>,
+  decisions: Array<{ question, decision, reasoning, alternatives? }>,
+  errors: Array<{ type, message, file?, line? }>
+}
+```
+
+### 3. ReviewResult
+
+Para agentes de review (code-reviewer, silent-failure-hunter).
+
+```javascript
+{
+  approved: boolean,
+  issues: Array<{ severity, type, file, line?, message, suggestion?, autoFixable }>,
+  summary: { critical, high, medium, low, info },
+  recommendation: 'approve' | 'request_changes' | 'needs_discussion'
+}
+```
+
+### 4. VerificationResult
+
+Para agentes de verificación (elsabro-verifier, elsabro-qa).
+
+```javascript
+{
+  passed: boolean,
+  tests: {
+    total: number,
+    passed: number,
+    failed: number,
+    skipped: number
+  },
+  typescript: {
+    passed: boolean,
+    errors: Array<{ file, line, message }>
+  },
+  lint: {
+    passed: boolean,
+    warnings: number,
+    errors: number
+  },
+  coverage?: {
+    statements: number,
+    branches: number,
+    functions: number,
+    lines: number
+  }
+}
+```
+
+### 5. PlanResult
+
+Para agentes de planificación (elsabro-planner).
+
+```javascript
+{
+  phases: Array<{
+    id: string,
+    name: string,
+    description: string,
+    tasks: Array<{ id, description, agent?, dependencies? }>,
+    estimatedComplexity: 'low' | 'medium' | 'high'
+  }>,
+  dependencies: Array<{ from, to }>,
+  risks: Array<{ description, severity, mitigation }>,
+  prerequisites: Array<string>
+}
+```
+
+---
+
+## API de Validación
+
+### SchemaValidator
+
+```javascript
+/**
+ * SchemaValidator
+ * Valida outputs de agentes contra schemas definidos
+ */
+class SchemaValidator {
+  constructor() {
+    this.schemas = new Map();
+    this.validationCache = new Map();
+
+    // Registrar schemas predefinidos
+    this.registerPredefinedSchemas();
+  }
+
+  /**
+   * Registra un schema
+   */
+  registerSchema(name, schema) {
+    this.schemas.set(name, {
+      name,
+      schema,
+      validator: this.compileValidator(schema)
+    });
+  }
+
+  /**
+   * Compila un validator desde JSON Schema o Zod
+   */
+  compileValidator(schema) {
+    // Si es Zod schema
+    if (schema._def) {
+      return (data) => {
+        const result = schema.safeParse(data);
+        return {
+          valid: result.success,
+          data: result.success ? result.data : null,
+          errors: result.success ? [] : result.error.errors.map(e => ({
+            path: e.path.join('.'),
+            message: e.message,
+            code: e.code
+          }))
+        };
+      };
+    }
+
+    // Si es JSON Schema
+    return (data) => this.validateJsonSchema(data, schema);
+  }
+
+  /**
+   * Valida JSON Schema manualmente
+   */
+  validateJsonSchema(data, schema) {
+    const errors = [];
+
+    // Validar tipo
+    if (schema.type && typeof data !== schema.type) {
+      if (!(schema.type === 'array' && Array.isArray(data))) {
+        errors.push({
+          path: '',
+          message: `Expected ${schema.type}, got ${typeof data}`,
+          code: 'invalid_type'
+        });
+        return { valid: false, data: null, errors };
+      }
+    }
+
+    // Validar required
+    if (schema.required && schema.type === 'object') {
+      for (const key of schema.required) {
+        if (!(key in data)) {
+          errors.push({
+            path: key,
+            message: `Missing required field: ${key}`,
+            code: 'missing_required'
+          });
+        }
+      }
+    }
+
+    // Validar propiedades
+    if (schema.properties && schema.type === 'object') {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        if (key in data) {
+          const result = this.validateJsonSchema(data[key], propSchema);
+          if (!result.valid) {
+            errors.push(...result.errors.map(e => ({
+              ...e,
+              path: e.path ? `${key}.${e.path}` : key
+            })));
+          }
+        }
+      }
+    }
+
+    // Validar array items
+    if (schema.items && Array.isArray(data)) {
+      data.forEach((item, index) => {
+        const result = this.validateJsonSchema(item, schema.items);
+        if (!result.valid) {
+          errors.push(...result.errors.map(e => ({
+            ...e,
+            path: `[${index}]${e.path ? '.' + e.path : ''}`
+          })));
+        }
+      });
+    }
+
+    // Validar enum
+    if (schema.enum && !schema.enum.includes(data)) {
+      errors.push({
+        path: '',
+        message: `Value must be one of: ${schema.enum.join(', ')}`,
+        code: 'invalid_enum'
+      });
+    }
+
+    // Validar string constraints
+    if (schema.type === 'string') {
+      if (schema.minLength && data.length < schema.minLength) {
+        errors.push({
+          path: '',
+          message: `String must be at least ${schema.minLength} characters`,
+          code: 'too_short'
+        });
+      }
+      if (schema.maxLength && data.length > schema.maxLength) {
+        errors.push({
+          path: '',
+          message: `String must be at most ${schema.maxLength} characters`,
+          code: 'too_long'
+        });
+      }
+    }
+
+    // Validar number constraints
+    if (schema.type === 'number' || schema.type === 'integer') {
+      if (schema.minimum !== undefined && data < schema.minimum) {
+        errors.push({
+          path: '',
+          message: `Number must be >= ${schema.minimum}`,
+          code: 'too_small'
+        });
+      }
+      if (schema.maximum !== undefined && data > schema.maximum) {
+        errors.push({
+          path: '',
+          message: `Number must be <= ${schema.maximum}`,
+          code: 'too_big'
+        });
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      data: errors.length === 0 ? data : null,
+      errors
+    };
+  }
+
+  /**
+   * Valida output contra un schema
+   */
+  validate(schemaName, data) {
+    const schemaEntry = this.schemas.get(schemaName);
+
+    if (!schemaEntry) {
+      return {
+        valid: false,
+        data: null,
+        errors: [{ path: '', message: `Schema not found: ${schemaName}`, code: 'schema_not_found' }]
+      };
+    }
+
+    return schemaEntry.validator(data);
+  }
+
+  /**
+   * Valida y transforma (aplica defaults, coerción)
+   */
+  validateAndTransform(schemaName, data, options = {}) {
+    const result = this.validate(schemaName, data);
+
+    if (!result.valid && options.coerce) {
+      // Intentar coerción de tipos
+      const coerced = this.coerceTypes(data, this.schemas.get(schemaName).schema);
+      const retryResult = this.validate(schemaName, coerced);
+
+      if (retryResult.valid) {
+        return { ...retryResult, coerced: true };
+      }
+    }
+
+    if (result.valid && options.applyDefaults) {
+      result.data = this.applyDefaults(result.data, this.schemas.get(schemaName).schema);
+    }
+
+    return result;
+  }
+
+  /**
+   * Intenta coercer tipos
+   */
+  coerceTypes(data, schema) {
+    if (schema.type === 'string' && typeof data !== 'string') {
+      return String(data);
+    }
+    if (schema.type === 'number' && typeof data === 'string') {
+      const num = parseFloat(data);
+      if (!isNaN(num)) return num;
+    }
+    if (schema.type === 'integer' && typeof data === 'string') {
+      const num = parseInt(data, 10);
+      if (!isNaN(num)) return num;
+    }
+    if (schema.type === 'boolean') {
+      if (data === 'true') return true;
+      if (data === 'false') return false;
+    }
+    if (schema.type === 'array' && !Array.isArray(data)) {
+      return [data];
+    }
+
+    if (schema.type === 'object' && schema.properties) {
+      const result = { ...data };
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        if (key in result) {
+          result[key] = this.coerceTypes(result[key], propSchema);
+        }
+      }
+      return result;
+    }
+
+    return data;
+  }
+
+  /**
+   * Aplica valores por defecto
+   */
+  applyDefaults(data, schema) {
+    if (schema.type !== 'object' || !schema.properties) {
+      return data;
+    }
+
+    const result = { ...data };
+
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      if (!(key in result) && propSchema.default !== undefined) {
+        result[key] = propSchema.default;
+      } else if (key in result && propSchema.type === 'object') {
+        result[key] = this.applyDefaults(result[key], propSchema);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Genera hints para corregir errores
+   */
+  generateHints(errors, schema) {
+    return errors.map(error => {
+      let hint = `Fix ${error.path || 'root'}: ${error.message}`;
+
+      if (error.code === 'missing_required') {
+        hint += `. Add the missing field.`;
+      } else if (error.code === 'invalid_type') {
+        hint += `. Check the data type.`;
+      } else if (error.code === 'invalid_enum') {
+        hint += `. Use one of the allowed values.`;
+      }
+
+      return { ...error, hint };
+    });
+  }
+
+  /**
+   * Registra schemas predefinidos
+   */
+  registerPredefinedSchemas() {
+    // AnalysisResult
+    this.registerSchema('analysis', {
+      type: 'object',
+      required: ['summary', 'files', 'recommendations'],
+      properties: {
+        summary: { type: 'string', minLength: 10, maxLength: 500 },
+        files: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['path', 'purpose'],
+            properties: {
+              path: { type: 'string' },
+              purpose: { type: 'string' },
+              complexity: { type: 'string', enum: ['low', 'medium', 'high'] },
+              linesOfCode: { type: 'integer', minimum: 0 }
+            }
+          }
+        },
+        recommendations: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['action', 'priority'],
+            properties: {
+              action: { type: 'string' },
+              priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
+              reason: { type: 'string' }
+            }
+          }
+        },
+        techDebt: {
+          type: 'object',
+          properties: {
+            score: { type: 'number', minimum: 0, maximum: 10 },
+            issues: { type: 'array', items: { type: 'string' } }
+          }
+        }
+      }
+    });
+
+    // ImplementationResult
+    this.registerSchema('implementation', {
+      type: 'object',
+      required: ['success'],
+      properties: {
+        success: { type: 'boolean' },
+        filesCreated: { type: 'array', default: [] },
+        filesModified: { type: 'array', default: [] },
+        testsCreated: { type: 'array', default: [] },
+        decisions: { type: 'array', default: [] },
+        errors: { type: 'array', default: [] }
+      }
+    });
+
+    // ReviewResult
+    this.registerSchema('review', {
+      type: 'object',
+      required: ['approved', 'issues', 'summary', 'recommendation'],
+      properties: {
+        approved: { type: 'boolean' },
+        issues: { type: 'array' },
+        summary: {
+          type: 'object',
+          required: ['critical', 'high', 'medium', 'low', 'info'],
+          properties: {
+            critical: { type: 'integer', minimum: 0 },
+            high: { type: 'integer', minimum: 0 },
+            medium: { type: 'integer', minimum: 0 },
+            low: { type: 'integer', minimum: 0 },
+            info: { type: 'integer', minimum: 0 }
+          }
+        },
+        recommendation: { type: 'string', enum: ['approve', 'request_changes', 'needs_discussion'] }
+      }
+    });
+
+    // VerificationResult
+    this.registerSchema('verification', {
+      type: 'object',
+      required: ['passed', 'tests', 'typescript', 'lint'],
+      properties: {
+        passed: { type: 'boolean' },
+        tests: {
+          type: 'object',
+          required: ['total', 'passed', 'failed', 'skipped'],
+          properties: {
+            total: { type: 'integer', minimum: 0 },
+            passed: { type: 'integer', minimum: 0 },
+            failed: { type: 'integer', minimum: 0 },
+            skipped: { type: 'integer', minimum: 0 }
+          }
+        },
+        typescript: {
+          type: 'object',
+          required: ['passed'],
+          properties: {
+            passed: { type: 'boolean' },
+            errors: { type: 'array' }
+          }
+        },
+        lint: {
+          type: 'object',
+          required: ['passed'],
+          properties: {
+            passed: { type: 'boolean' },
+            warnings: { type: 'integer', minimum: 0 },
+            errors: { type: 'integer', minimum: 0 }
+          }
+        },
+        coverage: {
+          type: 'object',
+          properties: {
+            statements: { type: 'number', minimum: 0, maximum: 100 },
+            branches: { type: 'number', minimum: 0, maximum: 100 },
+            functions: { type: 'number', minimum: 0, maximum: 100 },
+            lines: { type: 'number', minimum: 0, maximum: 100 }
+          }
+        }
+      }
+    });
+
+    // PlanResult
+    this.registerSchema('plan', {
+      type: 'object',
+      required: ['phases'],
+      properties: {
+        phases: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['id', 'name', 'tasks'],
+            properties: {
+              id: { type: 'string' },
+              name: { type: 'string' },
+              description: { type: 'string' },
+              tasks: { type: 'array' },
+              estimatedComplexity: { type: 'string', enum: ['low', 'medium', 'high'] }
+            }
+          }
+        },
+        dependencies: { type: 'array' },
+        risks: { type: 'array' },
+        prerequisites: { type: 'array', items: { type: 'string' } }
+      }
+    });
+  }
+}
+
+// Singleton instance
+let validatorInstance = null;
+
+function getValidator() {
+  if (!validatorInstance) {
+    validatorInstance = new SchemaValidator();
+  }
+  return validatorInstance;
+}
+
+module.exports = { SchemaValidator, getValidator };
+```
+
+---
+
+## Integración con Agentes
+
+### Validación de Output en Agent Execution
+
+```javascript
+async function executeAgentWithSchema(agent, inputs, expectedSchema) {
+  const validator = getValidator();
+  const telemetry = getTelemetry();
+
+  // Ejecutar agente
+  const rawOutput = await executeAgent(agent, inputs);
+
+  // Parsear output estructurado
+  const parsed = parseAgentOutput(rawOutput);
+
+  // Validar contra schema
+  const validation = validator.validateAndTransform(expectedSchema, parsed, {
+    coerce: true,
+    applyDefaults: true
+  });
+
+  if (!validation.valid) {
+    telemetry.logger.warn(`Agent output validation failed: ${agent.id}`, {
+      errors: validation.errors,
+      schema: expectedSchema
+    });
+
+    // Retry con hints
+    if (agent.config.retryOnSchemaError) {
+      const hints = validator.generateHints(validation.errors, expectedSchema);
+      const retryOutput = await executeAgent(agent, {
+        ...inputs,
+        _schemaHints: hints,
+        _expectedFormat: `Please return output matching this structure: ${JSON.stringify(expectedSchema)}`
+      });
+
+      const retryValidation = validator.validate(expectedSchema, parseAgentOutput(retryOutput));
+      if (retryValidation.valid) {
+        return retryValidation.data;
+      }
+    }
+
+    throw new SchemaValidationError(validation.errors, expectedSchema);
+  }
+
+  return validation.data;
+}
+```
+
+### Declaración de Schema en Flow
+
+```json
+{
+  "id": "analyze",
+  "type": "agent",
+  "agent": "elsabro-analyst",
+  "outputSchema": "analysis",
+  "config": {
+    "retryOnSchemaError": true,
+    "maxSchemaRetries": 2
+  }
+}
+```
+
+---
+
+## Comandos de Usuario
+
+### /elsabro:schema
+
+```bash
+/elsabro:schema list              # Listar schemas disponibles
+/elsabro:schema show <name>       # Mostrar schema específico
+/elsabro:schema validate <file>   # Validar archivo contra schema
+/elsabro:schema create            # Crear nuevo schema (interactivo)
+```
+
+---
+
+## Configuración
+
+### .planning/schemas-config.json
+
+```json
+{
+  "schemas": {
+    "validation": {
+      "strict": true,
+      "coerceTypes": true,
+      "applyDefaults": true,
+      "retryOnError": true,
+      "maxRetries": 2
+    },
+    "customSchemas": {
+      "directory": ".planning/schemas/",
+      "autoLoad": true
+    },
+    "agentDefaults": {
+      "elsabro-analyst": "analysis",
+      "elsabro-executor": "implementation",
+      "elsabro-verifier": "verification",
+      "elsabro-planner": "plan",
+      "code-reviewer": "review",
+      "pr-review-toolkit:code-reviewer": "review",
+      "pr-review-toolkit:silent-failure-hunter": "review"
+    }
+  }
+}
+```