sinapse-ai 5.0.8 → 6.0.1

package/docs/es/architecture/coding-standards.md

@@ -1,896 +0,0 @@
-<!-- Traduccion: ES | Original: /docs/en/architecture/coding-standards.md | Sincronizacion: 2026-01-26 -->
-
-> ⚠️ **OBSOLETO**: Este archivo se mantiene solo por compatibilidad hacia atras.
->
-> **Version oficial:** [docs/framework/coding-standards.md](../framework/coding-standards.md)
->
-> Este archivo sera eliminado en Q2 2026 despues de la consolidacion completa a `docs/framework/`.
-
----
-
-# Estandares de Codigo SINAPSE
-
-> 🌐 [EN](../../architecture/coding-standards.md) | [PT](../../pt/architecture/coding-standards.md) | **ES**
-
----
-
-**Version:** 1.1
-**Ultima Actualizacion:** 2025-12-14
-**Estado:** OBSOLETO - Ver docs/framework/coding-standards.md
-**Aviso de Migracion:** Este documento migrara al repositorio `SinapseAI/sinapse-ai` en Q2 2026 (ver Decision 005)
-
----
-
-## 📋 Tabla de Contenidos
-
-- [Descripcion General](#descripcion-general)
-- [Estandares JavaScript/TypeScript](#estandares-javascripttypescript)
-- [Organizacion de Archivos](#organizacion-de-archivos)
-- [Convenciones de Nomenclatura](#convenciones-de-nomenclatura)
-- [Calidad de Codigo](#calidad-de-codigo)
-- [Estandares de Documentacion](#estandares-de-documentacion)
-- [Estandares de Testing](#estandares-de-testing)
-- [Convenciones de Git](#convenciones-de-git)
-- [Estandares de Seguridad](#estandares-de-seguridad)
-
----
-
-## Descripcion General
-
-Este documento define los estandares oficiales de codigo para el desarrollo del framework SINAPSE. Todas las contribuciones de codigo deben adherirse a estos estandares para asegurar consistencia, mantenibilidad y calidad.
-
-**Aplicacion:**
-
-- ESLint (automatizado)
-- Prettier (automatizado)
-- Revision de CodeRabbit (automatizado)
-- Revision humana (manual)
-
----
-
-## Estandares JavaScript/TypeScript
-
-### Version del Lenguaje
-
-```javascript
-// Objetivo: ES2022 (Node.js 18+)
-// TypeScript: 5.x
-
-// ✅ CORRECTO: Sintaxis moderna
-const data = await fetchData();
-const { id, name } = data;
-
-// ❌ INCORRECTO: Sintaxis obsoleta
-fetchData().then(function (data) {
-  var id = data.id;
-  var name = data.name;
-});
-```
-
-### Configuracion de TypeScript
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "commonjs",
-    "lib": ["ES2022"],
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "declaration": true,
-    "outDir": "./dist",
-    "rootDir": "./src"
-  }
-}
-```
-
-### Estilo de Codigo
-
-#### Indentacion y Formato
-
-```javascript
-// ✅ CORRECTO: 2 espacios de indentacion
-function processAgent(agent) {
-  if (agent.enabled) {
-    return loadAgent(agent);
-  }
-  return null;
-}
-
-// ❌ INCORRECTO: 4 espacios o tabs
-function processAgent(agent) {
-  if (agent.enabled) {
-    return loadAgent(agent);
-  }
-  return null;
-}
-```
-
-**Configuracion de Prettier:**
-
-```json
-{
-  "printWidth": 100,
-  "tabWidth": 2,
-  "useTabs": false,
-  "semi": true,
-  "singleQuote": true,
-  "trailingComma": "es5",
-  "bracketSpacing": true,
-  "arrowParens": "always"
-}
-```
-
-#### Longitud de Linea
-
-```javascript
-// ✅ CORRECTO: Maximo 100 caracteres
-const result = await executeTask(taskName, taskArgs, { timeout: 5000, retry: 3 });
-
-// ❌ INCORRECTO: Mas de 100 caracteres
-const result = await executeTask(taskName, taskArgs, {
-  timeout: 5000,
-  retry: 3,
-  failureCallback: onFailure,
-});
-```
-
-#### Comillas
-
-```javascript
-// ✅ CORRECTO: Comillas simples para strings
-const agentName = 'developer';
-const message = `Agent ${agentName} activated`;
-
-// ❌ INCORRECTO: Comillas dobles (excepto JSON)
-const agentName = 'developer';
-```
-
-### Patrones Modernos de JavaScript
-
-#### Async/Await (Preferido)
-
-```javascript
-// ✅ CORRECTO: async/await
-async function loadAgent(agentId) {
-  try {
-    const agent = await fetchAgent(agentId);
-    const config = await loadConfig(agent.configPath);
-    return { agent, config };
-  } catch (error) {
-    console.error(`Error al cargar agente ${agentId}:`, error);
-    throw error;
-  }
-}
-
-// ❌ INCORRECTO: Cadenas de Promise
-function loadAgent(agentId) {
-  return fetchAgent(agentId)
-    .then((agent) => loadConfig(agent.configPath).then((config) => ({ agent, config })))
-    .catch((error) => {
-      console.error(`Error al cargar agente ${agentId}:`, error);
-      throw error;
-    });
-}
-```
-
-#### Desestructuracion
-
-```javascript
-// ✅ CORRECTO: Desestructuracion
-const { name, id, enabled } = agent;
-const [first, second, ...rest] = items;
-
-// ❌ INCORRECTO: Extraccion manual
-const name = agent.name;
-const id = agent.id;
-const enabled = agent.enabled;
-```
-
-#### Funciones Flecha
-
-```javascript
-// ✅ CORRECTO: Funciones flecha para callbacks
-const activeAgents = agents.filter((agent) => agent.enabled);
-const agentNames = agents.map((agent) => agent.name);
-
-// ❌ INCORRECTO: Funciones tradicionales para callbacks simples
-const activeAgents = agents.filter(function (agent) {
-  return agent.enabled;
-});
-```
-
-#### Template Literals
-
-```javascript
-// ✅ CORRECTO: Template literals para interpolacion de strings
-const message = `Agente ${agentName} cargado exitosamente`;
-const path = `${baseDir}/${agentId}/config.yaml`;
-
-// ❌ INCORRECTO: Concatenacion de strings
-const message = 'Agente ' + agentName + ' cargado exitosamente';
-const path = baseDir + '/' + agentId + '/config.yaml';
-```
-
-### Manejo de Errores
-
-```javascript
-// ✅ CORRECTO: Manejo de errores especifico con contexto
-async function executeTask(taskName) {
-  try {
-    const task = await loadTask(taskName);
-    return await task.execute();
-  } catch (error) {
-    console.error(`Ejecucion de tarea fallida [${taskName}]:`, error);
-    throw new Error(`Error al ejecutar tarea "${taskName}": ${error.message}`);
-  }
-}
-
-// ❌ INCORRECTO: Fallos silenciosos o errores genericos
-async function executeTask(taskName) {
-  try {
-    const task = await loadTask(taskName);
-    return await task.execute();
-  } catch (error) {
-    console.log('Error:', error);
-    return null; // Fallo silencioso
-  }
-}
-```
-
----
-
-## Organizacion de Archivos
-
-### Estructura de Directorios
-
-```
-.sinapse-ai/
-├── agents/              # Definiciones de agentes (YAML + Markdown)
-├── tasks/               # Workflows de tareas (Markdown)
-├── templates/           # Plantillas de documentos (YAML/Markdown)
-├── workflows/           # Workflows multi-paso (YAML)
-├── checklists/          # Checklists de validacion (Markdown)
-├── data/                # Base de conocimiento (Markdown)
-├── utils/               # Scripts de utilidad (JavaScript)
-├── tools/               # Integraciones de herramientas (YAML)
-└── elicitation/         # Motores de elicitacion (JavaScript)
-
-docs/
-├── architecture/        # Decisiones de arquitectura especificas del proyecto
-├── framework/           # Documentacion oficial del framework (migra a REPO 1)
-├── stories/             # Historias de desarrollo
-├── epics/               # Planificacion de epics
-└── guides/              # Guias practicas
-```
-
-### Nomenclatura de Archivos
-
-```javascript
-// ✅ CORRECTO: Kebab-case para archivos
-agent - executor.js;
-task - runner.js;
-greeting - builder.js;
-context - detector.js;
-
-// ❌ INCORRECTO: camelCase o PascalCase para archivos
-agentExecutor.js;
-TaskRunner.js;
-GreetingBuilder.js;
-```
-
-### Estructura de Modulos
-
-```javascript
-// ✅ CORRECTO: Estructura de modulo clara
-// Archivo: agent-executor.js
-
-// 1. Imports
-const fs = require('fs').promises;
-const yaml = require('yaml');
-const { loadConfig } = require('./config-loader');
-
-// 2. Constantes
-const DEFAULT_TIMEOUT = 5000;
-const MAX_RETRIES = 3;
-
-// 3. Funciones auxiliares (privadas)
-function validateAgent(agent) {
-  // ...
-}
-
-// 4. Exports principales (API publica)
-async function executeAgent(agentId, args) {
-  // ...
-}
-
-async function loadAgent(agentId) {
-  // ...
-}
-
-// 5. Exports
-module.exports = {
-  executeAgent,
-  loadAgent,
-};
-```
-
----
-
-## Convenciones de Nomenclatura
-
-### Variables y Funciones
-
-```javascript
-// ✅ CORRECTO: camelCase para variables y funciones
-const agentName = 'developer';
-const taskResult = await executeTask();
-
-function loadAgentConfig(agentId) {
-  // ...
-}
-
-async function fetchAgentData(agentId) {
-  // ...
-}
-
-// ❌ INCORRECTO: snake_case o PascalCase
-const agent_name = 'developer';
-const TaskResult = await executeTask();
-
-function LoadAgentConfig(agentId) {
-  // ...
-}
-```
-
-### Clases
-
-```javascript
-// ✅ CORRECTO: PascalCase para clases
-class AgentExecutor {
-  constructor(config) {
-    this.config = config;
-  }
-
-  async execute(agentId) {
-    // ...
-  }
-}
-
-class TaskRunner {
-  // ...
-}
-
-// ❌ INCORRECTO: camelCase o snake_case
-class agentExecutor {
-  // ...
-}
-
-class task_runner {
-  // ...
-}
-```
-
-### Constantes
-
-```javascript
-// ✅ CORRECTO: SCREAMING_SNAKE_CASE para constantes verdaderas
-const MAX_RETRY_ATTEMPTS = 3;
-const DEFAULT_TIMEOUT_MS = 5000;
-const AGENT_STATUS_ACTIVE = 'active';
-
-// ❌ INCORRECTO: camelCase o minusculas
-const maxRetryAttempts = 3;
-const defaulttimeout = 5000;
-```
-
-### Miembros Privados
-
-```javascript
-// ✅ CORRECTO: Prefijo con guion bajo para privados (convencion)
-class AgentManager {
-  constructor() {
-    this._cache = new Map();
-    this._isInitialized = false;
-  }
-
-  _loadFromCache(id) {
-    // Helper privado
-    return this._cache.get(id);
-  }
-
-  async getAgent(id) {
-    // API publica
-    return this._loadFromCache(id) || (await this._fetchAgent(id));
-  }
-}
-```
-
-### Variables Booleanas
-
-```javascript
-// ✅ CORRECTO: Prefijo is/has/should
-const isEnabled = true;
-const hasPermission = false;
-const shouldRetry = checkCondition();
-
-// ❌ INCORRECTO: Nombres ambiguos
-const enabled = true;
-const permission = false;
-const retry = checkCondition();
-```
-
----
-
-## Calidad de Codigo
-
-### Configuracion de ESLint
-
-```json
-{
-  "env": {
-    "node": true,
-    "es2022": true
-  },
-  "extends": ["eslint:recommended"],
-  "parserOptions": {
-    "ecmaVersion": 13,
-    "sourceType": "module"
-  },
-  "rules": {
-    "no-console": "off",
-    "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
-    "prefer-const": "error",
-    "no-var": "error",
-    "eqeqeq": ["error", "always"],
-    "curly": ["error", "all"],
-    "brace-style": ["error", "1tbs"],
-    "comma-dangle": ["error", "es5"],
-    "quotes": ["error", "single"],
-    "semi": ["error", "always"]
-  }
-}
-```
-
-### Complejidad de Codigo
-
-```javascript
-// ✅ CORRECTO: Baja complejidad ciclomatica (< 10)
-function processAgent(agent) {
-  if (!agent.enabled) return null;
-
-  const config = loadConfig(agent.configPath);
-  const result = executeAgent(agent, config);
-
-  return result;
-}
-
-// ❌ INCORRECTO: Alta complejidad ciclomatica
-function processAgent(agent) {
-  if (agent.type === 'dev') {
-    if (agent.mode === 'yolo') {
-      if (agent.hasStory) {
-        // ... logica anidada
-      } else {
-        // ... mas logica anidada
-      }
-    } else {
-      // ... mas ramas
-    }
-  } else if (agent.type === 'qa') {
-    // ... mas ramas
-  }
-  // ... aun mas complejidad
-}
-```
-
-**Refactorizar funciones complejas:**
-
-```javascript
-// ✅ CORRECTO: Funciones auxiliares extraidas
-function processAgent(agent) {
-  if (!agent.enabled) return null;
-
-  if (agent.type === 'dev') {
-    return processDevAgent(agent);
-  }
-
-  if (agent.type === 'qa') {
-    return processQaAgent(agent);
-  }
-
-  return processDefaultAgent(agent);
-}
-```
-
-### Principio DRY
-
-```javascript
-// ✅ CORRECTO: Funcion reutilizable
-function validateAndLoad(filePath, schema) {
-  const content = fs.readFileSync(filePath, 'utf8');
-  const data = yaml.parse(content);
-
-  if (!schema.validate(data)) {
-    throw new Error(`Schema invalido: ${filePath}`);
-  }
-
-  return data;
-}
-
-const agent = validateAndLoad('agent.yaml', agentSchema);
-const task = validateAndLoad('task.yaml', taskSchema);
-
-// ❌ INCORRECTO: Codigo repetido
-const agentContent = fs.readFileSync('agent.yaml', 'utf8');
-const agentData = yaml.parse(agentContent);
-if (!agentSchema.validate(agentData)) {
-  throw new Error('Schema de agente invalido');
-}
-
-const taskContent = fs.readFileSync('task.yaml', 'utf8');
-const taskData = yaml.parse(taskContent);
-if (!taskSchema.validate(taskData)) {
-  throw new Error('Schema de tarea invalido');
-}
-```
-
----
-
-## Estandares de Documentacion
-
-### Comentarios JSDoc
-
-```javascript
-/**
- * Carga y ejecuta un agente SINAPSE
- *
- * @param {string} agentId - Identificador unico del agente
- * @param {Object} args - Argumentos de ejecucion del agente
- * @param {boolean} args.yoloMode - Habilitar modo autonomo
- * @param {string} args.storyPath - Ruta al archivo de historia (opcional)
- * @param {number} [timeout=5000] - Timeout de ejecucion en milisegundos
- * @returns {Promise<Object>} Resultado de la ejecucion del agente
- * @throws {Error} Si el agente no se encuentra o la ejecucion falla
- *
- * @example
- * const result = await executeAgent('dev', {
- *   yoloMode: true,
- *   storyPath: 'docs/stories/story-6.1.2.5.md'
- * });
- */
-async function executeAgent(agentId, args, timeout = 5000) {
-  // Implementacion
-}
-```
-
-### Comentarios en Linea
-
-```javascript
-// ✅ CORRECTO: Explicar POR QUE, no QUE
-// Cache de agentes para evitar re-parseo de YAML en cada activacion (optimizacion de rendimiento)
-const agentCache = new Map();
-
-// Log de decisiones requerido para rollback en modo yolo (requisito de Historia 6.1.2.6)
-if (yoloMode) {
-  await createDecisionLog(storyId);
-}
-
-// ❌ INCORRECTO: Decir lo obvio
-// Crear un nuevo Map
-const agentCache = new Map();
-
-// Si yolo mode es verdadero
-if (yoloMode) {
-  await createDecisionLog(storyId);
-}
-```
-
-### Archivos README
-
-Cada modulo/directorio debe tener un README.md:
-
-```markdown
-# Agent Executor
-
-**Proposito:** Carga y ejecuta agentes SINAPSE con gestion de configuracion.
-
-## Uso
-
-\`\`\`javascript
-const { executeAgent } = require('./agent-executor');
-
-const result = await executeAgent('dev', {
-yoloMode: true,
-storyPath: 'docs/stories/story-6.1.2.5.md'
-});
-\`\`\`
-
-## API
-
-- `executeAgent(agentId, args, timeout)` - Ejecutar agente
-- `loadAgent(agentId)` - Cargar configuracion de agente
-
-## Dependencias
-
-- `yaml` - Parsing de YAML
-- `fs/promises` - Operaciones de sistema de archivos
-```
-
----
-
-## Estandares de Testing
-
-### Nomenclatura de Archivos de Test
-
-```bash
-# Tests unitarios
-tests/unit/context-detector.test.js
-tests/unit/git-config-detector.test.js
-
-# Tests de integracion
-tests/integration/contextual-greeting.test.js
-tests/integration/workflow-navigation.test.js
-
-# Tests E2E
-tests/e2e/agent-activation.test.js
-```
-
-### Estructura de Tests
-
-```javascript
-// ✅ CORRECTO: Nombres de test descriptivos con Given-When-Then
-describe('ContextDetector', () => {
-  describe('detectSessionType', () => {
-    it('deberia retornar "new" cuando el historial de conversacion esta vacio', async () => {
-      // Given (Dado)
-      const conversationHistory = [];
-      const sessionFile = null;
-
-      // When (Cuando)
-      const result = await detectSessionType(conversationHistory, sessionFile);
-
-      // Then (Entonces)
-      expect(result).toBe('new');
-    });
-
-    it('deberia retornar "workflow" cuando el patron de comando coincide con story_development', async () => {
-      // Given (Dado)
-      const conversationHistory = [{ command: 'validate-story-draft' }, { command: 'develop' }];
-
-      // When (Cuando)
-      const result = await detectSessionType(conversationHistory, null);
-
-      // Then (Entonces)
-      expect(result).toBe('workflow');
-    });
-  });
-});
-```
-
-### Cobertura de Codigo
-
-- **Minimo:** 80% para todos los modulos nuevos
-- **Objetivo:** 90% para modulos core
-- **Critico:** 100% para modulos de seguridad/validacion
-
-```bash
-# Ejecutar cobertura
-npm test -- --coverage
-
-# Umbrales de cobertura en package.json
-{
-  "jest": {
-    "coverageThreshold": {
-      "global": {
-        "branches": 80,
-        "functions": 80,
-        "lines": 80,
-        "statements": 80
-      }
-    }
-  }
-}
-```
-
----
-
-## Convenciones de Git
-
-### Mensajes de Commit
-
-```bash
-# ✅ CORRECTO: Formato de Conventional Commits
-feat: implementar sistema de saludo contextual de agentes [Story 6.1.2.5]
-fix: resolver problema de invalidacion de cache de git config [Story 6.1.2.5]
-docs: actualizar estandares de codigo con configuracion TypeScript
-chore: actualizar configuracion de ESLint
-refactor: extraer greeting builder a modulo separado
-test: agregar tests unitarios para WorkflowNavigator
-
-# ❌ INCORRECTO: Vagos o no descriptivos
-actualizar archivos
-arreglar bug
-cambios
-wip
-```
-
-**Formato:**
-
-```
-<tipo>: <descripcion> [Story <id>]
-
-<cuerpo opcional>
-
-<pie opcional>
-```
-
-**Tipos:**
-
-- `feat`: Nueva funcionalidad
-- `fix`: Correccion de bug
-- `docs`: Cambios en documentacion
-- `chore`: Cambios de build/herramientas
-- `refactor`: Refactorizacion de codigo (sin cambio funcional)
-- `test`: Adiciones/modificaciones de tests
-- `perf`: Mejoras de rendimiento
-- `style`: Cambios de estilo de codigo (formato, etc.)
-
-### Nomenclatura de Ramas
-
-```bash
-# ✅ CORRECTO: Nombres de rama descriptivos
-feature/story-6.1.2.5-contextual-greeting
-fix/git-config-cache-ttl
-refactor/agent-executor-optimization
-docs/update-coding-standards
-
-# ❌ INCORRECTO: Nombres de rama vagos
-update
-fix
-my-branch
-```
-
----
-
-## Estandares de Seguridad
-
-### Validacion de Entrada
-
-```javascript
-// ✅ CORRECTO: Validar todas las entradas externas
-function executeCommand(command) {
-  // Validacion de whitelist
-  const allowedCommands = ['help', 'develop', 'review', 'deploy'];
-
-  if (!allowedCommands.includes(command)) {
-    throw new Error(`Comando invalido: ${command}`);
-  }
-
-  return runCommand(command);
-}
-
-// ❌ INCORRECTO: Sin validacion
-function executeCommand(command) {
-  return eval(command); // NUNCA HACER ESTO
-}
-```
-
-### Proteccion contra Path Traversal
-
-```javascript
-// ✅ CORRECTO: Validar rutas de archivo
-const path = require('path');
-
-function loadFile(filePath) {
-  const basePath = path.resolve(__dirname, '.sinapse-ai');
-  const resolvedPath = path.resolve(basePath, filePath);
-
-  // Prevenir directory traversal
-  if (!resolvedPath.startsWith(basePath)) {
-    throw new Error('Ruta de archivo invalida');
-  }
-
-  return fs.readFile(resolvedPath, 'utf8');
-}
-
-// ❌ INCORRECTO: Uso directo de ruta
-function loadFile(filePath) {
-  return fs.readFile(filePath, 'utf8'); // Vulnerable a ../../../etc/passwd
-}
-```
-
-### Gestion de Secretos
-
-```javascript
-// ✅ CORRECTO: Usar variables de entorno
-const apiKey = process.env.CLICKUP_API_KEY;
-
-if (!apiKey) {
-  throw new Error('Variable de entorno CLICKUP_API_KEY no configurada');
-}
-
-// ❌ INCORRECTO: Secretos hardcodeados
-const apiKey = 'pk_12345678_abcdefgh'; // NUNCA HACER ESTO
-```
-
-### Seguridad de Dependencias
-
-```bash
-# Auditorias de seguridad regulares
-npm audit
-npm audit fix
-
-# Usar Snyk o similar para monitoreo continuo
-```
-
----
-
-## Aplicacion
-
-### Pre-commit Hooks
-
-```bash
-# .husky/pre-commit
-#!/bin/sh
-npm run lint
-npm run typecheck
-npm test
-```
-
-### Pipeline CI/CD
-
-```yaml
-# .github/workflows/ci.yml
-name: CI
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      - run: npm ci
-      - run: npm run lint
-      - run: npm run typecheck
-      - run: npm test -- --coverage
-      - run: npm audit
-```
-
-### Integracion con CodeRabbit
-
-Todos los PRs son revisados automaticamente por CodeRabbit para:
-
-- Problemas de calidad de codigo
-- Vulnerabilidades de seguridad
-- Problemas de rendimiento
-- Violaciones de mejores practicas
-- Gaps en cobertura de tests
-
----
-
-## Historial de Versiones
-
-| Version | Fecha      | Cambios                                                          | Autor            |
-| ------- | ---------- | ---------------------------------------------------------------- | ---------------- |
-| 1.0     | 2025-01-15 | Documento inicial de estandares de codigo                        | Aria (architect) |
-| 1.1     | 2025-12-14 | Actualizado aviso de migracion a SinapseAI/sinapse-ai [Story 6.10] | Dex (dev)        |
-
----
-
-**Documentos Relacionados:**
-
-- [Tech Stack](./tech-stack.md)
-- [Source Tree](./source-tree.md)
-
----
-
-_Este es un estandar oficial del framework SINAPSE. Todas las contribuciones de codigo deben cumplir con el._