diff --git a/backend b/backend index 25d59cd..fd9f700 160000 --- a/backend +++ b/backend @@ -1 +1 @@ -Subproject commit 25d59cd031f9577af1a3e3fd7870887ca6db74be +Subproject commit fd9f7004bc8b02a01aba03addcdbf881fdc9ca9b diff --git a/database b/database index 6235880..8ed6366 160000 --- a/database +++ b/database @@ -1 +1 @@ -Subproject commit 6235880380d02c25ddca9e4f10cc79090c1d72e1 +Subproject commit 8ed6366b3006457a5a16dfa58fb3ad0c09eb7ac5 diff --git a/frontend b/frontend index 35f98c8..36a8487 160000 --- a/frontend +++ b/frontend @@ -1 +1 @@ -Subproject commit 35f98c825860ee86b4de996385f7f3d22e50e7cc +Subproject commit 36a84875a4367a91b303c8159454594f84d7aeb9 diff --git a/orchestration/_MAP.md b/orchestration/_MAP.md index f6d7259..ad07aa2 100644 --- a/orchestration/_MAP.md +++ b/orchestration/_MAP.md @@ -1,48 +1,102 @@ # MAPA DE ORQUESTACION: clinica-veterinaria **Proyecto:** clinica-veterinaria -**Nivel:** NIVEL_2B.2 -**Sistema:** NEXUS v4.0 + SIMCO + SAAD -**Ultima actualizacion:** 2026-01-10 +**Nivel:** SUB-CONSUMER (hereda de erp-clinicas) +**Sistema:** SIMCO-ESTANDAR-ORCHESTRATION v1.0.0 +**Ultima actualizacion:** 2026-01-24 --- -## Estructura +## Estructura Estandarizada ``` orchestration/ -├── 00-guidelines/ -│ └── CONTEXTO-PROYECTO.md -├── environment/ -├── inventarios/ -├── trazas/ -├── CONTEXT-MAP.yml -├── PROJECT-STATUS.md -├── PROXIMA-ACCION.md -└── _MAP.md +├── 00-guidelines/ # Guidelines locales del proyecto +│ ├── CONTEXTO-PROYECTO.md +│ ├── HERENCIA-ERP-CLINICAS.md +│ ├── HERENCIA-ERP-CORE.md +│ └── HERENCIA-SIMCO.md +├── inventarios/ # Inventarios del proyecto +│ ├── BACKEND_INVENTORY.yml +│ ├── DATABASE_INVENTORY.yml +│ ├── FRONTEND_INVENTORY.yml +│ └── MASTER_INVENTORY.yml +├── trazas/ # Trazas de ejecucion +│ ├── REPORTE-EJECUCION-SPRINT7-2026-01-07.md +│ └── TRAZA-TAREAS-DATABASE.md +├── _archive/ # Contenido archivado (no estandar) +│ ├── _definitions/ +│ ├── _refs/ +│ ├── agents/ +│ ├── directivas/ +│ ├── environment/ +│ └── referencias/ +├── _inheritance.yml # Modelo de herencia +├── _MAP.md # Este archivo +├── BOOTLOADER.md # Arranque del proyecto +├── CONTEXT-MAP.yml # Mapa de contexto NEXUS +├── DEPENDENCY-GRAPH.yml # Grafo de dependencias +├── MAPA-DOCUMENTACION.yml # Mapa de documentacion +├── PROJECT-PROFILE.yml # Perfil del proyecto +├── PROJECT-STATUS.md # Estado actual +├── PROXIMA-ACCION.md # Siguiente accion +└── TRACEABILITY.yml # Trazabilidad ``` --- +## Archivos Obligatorios (10/10) + +| # | Archivo | Estado | +|---|---------|--------| +| 1 | _inheritance.yml | OK | +| 2 | _MAP.md | OK | +| 3 | BOOTLOADER.md | OK | +| 4 | CONTEXT-MAP.yml | OK | +| 5 | DEPENDENCY-GRAPH.yml | OK | +| 6 | MAPA-DOCUMENTACION.yml | OK | +| 7 | PROJECT-PROFILE.yml | OK | +| 8 | PROJECT-STATUS.md | OK | +| 9 | PROXIMA-ACCION.md | OK | +| 10 | TRACEABILITY.yml | OK | + +--- + +## Carpetas Obligatorias (4/4) + +| Carpeta | Estado | Contenido | +|---------|--------|-----------| +| 00-guidelines/ | OK | 4 archivos | +| inventarios/ | OK | 4 archivos | +| trazas/ | OK | 2 archivos | +| _archive/ | OK | Contenido no estandar archivado | + +--- + ## Navegacion | Destino | Enlace | |---------|--------| -| Documentacion | [../docs/_MAP.md](../docs/_MAP.md) | -| Orchestration Central | [../../orchestration/_MAP.md](../../orchestration/_MAP.md) | -| Directivas SIMCO | [../../orchestration/directivas/simco/_INDEX.md](../../orchestration/directivas/simco/_INDEX.md) | +| Padre: erp-clinicas | [../../erp-clinicas/orchestration/_MAP.md](../../erp-clinicas/orchestration/_MAP.md) | +| Orchestration Central | [../../../orchestration/_MAP.md](../../../orchestration/_MAP.md) | +| Documentacion Proyecto | [../docs/_MAP.md](../docs/_MAP.md) | --- -## Archivos Principales +## Nota sobre _archive/ -| Archivo | Proposito | -|---------|-----------| -| CONTEXT-MAP.yml | Configuracion contexto | -| CONTEXTO-PROYECTO.md | Descripcion proyecto | -| PROJECT-STATUS.md | Estado actual | -| PROXIMA-ACCION.md | Siguiente tarea | +El contenido en `_archive/` fue movido durante la reestructuracion a SIMCO-ESTANDAR-ORCHESTRATION v1.0.0. +Este contenido era duplicacion de directivas heredadas del workspace padre. +Los proyectos SUB-CONSUMER heredan directivas automaticamente y no requieren copias locales. + +**Contenido archivado:** +- `_definitions/` - Checklists, protocolos, validaciones (heredar de workspace) +- `_refs/` - Referencias (heredar de workspace) +- `agents/` - Perfiles de agentes (heredar de erp-clinicas) +- `directivas/` - Principios, SIMCO, triggers (heredar de workspace) +- `environment/` - Inventario de ambiente (mover a inventarios/ si necesario) +- `referencias/` - Dependencias ERP (mover a inventarios/ si necesario) --- -**Actualizado:** 2026-01-10 +**Reestructurado:** 2026-01-24 segun SIMCO-ESTANDAR-ORCHESTRATION v1.0.0 diff --git a/orchestration/_definitions/_INDEX.yml b/orchestration/_archive/_definitions/_INDEX.yml similarity index 100% rename from orchestration/_definitions/_INDEX.yml rename to orchestration/_archive/_definitions/_INDEX.yml diff --git a/orchestration/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md b/orchestration/_archive/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md similarity index 100% rename from orchestration/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md rename to orchestration/_archive/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md diff --git a/orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md b/orchestration/_archive/_definitions/checklists/CHECKLIST-POST-TASK.md similarity index 100% rename from orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md rename to orchestration/_archive/_definitions/checklists/CHECKLIST-POST-TASK.md diff --git a/orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md b/orchestration/_archive/_definitions/checklists/CHECKLIST-PRE-CREATE.md similarity index 100% rename from orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md rename to orchestration/_archive/_definitions/checklists/CHECKLIST-PRE-CREATE.md diff --git a/orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md b/orchestration/_archive/_definitions/checklists/CHECKLIST-PRE-MODIFY.md similarity index 100% rename from orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md rename to orchestration/_archive/_definitions/checklists/CHECKLIST-PRE-MODIFY.md diff --git a/orchestration/_definitions/protocols/CAPVED-CYCLE.md b/orchestration/_archive/_definitions/protocols/CAPVED-CYCLE.md similarity index 100% rename from orchestration/_definitions/protocols/CAPVED-CYCLE.md rename to orchestration/_archive/_definitions/protocols/CAPVED-CYCLE.md diff --git a/orchestration/_definitions/protocols/CCA-PROTOCOL.md b/orchestration/_archive/_definitions/protocols/CCA-PROTOCOL.md similarity index 100% rename from orchestration/_definitions/protocols/CCA-PROTOCOL.md rename to orchestration/_archive/_definitions/protocols/CCA-PROTOCOL.md diff --git a/orchestration/_definitions/validations/VALIDATION-BACKEND.md b/orchestration/_archive/_definitions/validations/VALIDATION-BACKEND.md similarity index 100% rename from orchestration/_definitions/validations/VALIDATION-BACKEND.md rename to orchestration/_archive/_definitions/validations/VALIDATION-BACKEND.md diff --git a/orchestration/_definitions/validations/VALIDATION-DDL.md b/orchestration/_archive/_definitions/validations/VALIDATION-DDL.md similarity index 100% rename from orchestration/_definitions/validations/VALIDATION-DDL.md rename to orchestration/_archive/_definitions/validations/VALIDATION-DDL.md diff --git a/orchestration/_definitions/validations/VALIDATION-FRONTEND.md b/orchestration/_archive/_definitions/validations/VALIDATION-FRONTEND.md similarity index 100% rename from orchestration/_definitions/validations/VALIDATION-FRONTEND.md rename to orchestration/_archive/_definitions/validations/VALIDATION-FRONTEND.md diff --git a/orchestration/_refs/WS-REFERENCES.yml b/orchestration/_archive/_refs/WS-REFERENCES.yml similarity index 100% rename from orchestration/_refs/WS-REFERENCES.yml rename to orchestration/_archive/_refs/WS-REFERENCES.yml diff --git a/orchestration/agents/perfiles/PERFIL-DDL-VET-AGENT.yml b/orchestration/_archive/agents/perfiles/PERFIL-DDL-VET-AGENT.yml similarity index 100% rename from orchestration/agents/perfiles/PERFIL-DDL-VET-AGENT.yml rename to orchestration/_archive/agents/perfiles/PERFIL-DDL-VET-AGENT.yml diff --git a/orchestration/agents/perfiles/PERFIL-VETERINARIO-AGENT.yml b/orchestration/_archive/agents/perfiles/PERFIL-VETERINARIO-AGENT.yml similarity index 100% rename from orchestration/agents/perfiles/PERFIL-VETERINARIO-AGENT.yml rename to orchestration/_archive/agents/perfiles/PERFIL-VETERINARIO-AGENT.yml diff --git a/orchestration/agents/perfiles/_INDEX.yml b/orchestration/_archive/agents/perfiles/_INDEX.yml similarity index 100% rename from orchestration/agents/perfiles/_INDEX.yml rename to orchestration/_archive/agents/perfiles/_INDEX.yml diff --git a/orchestration/directivas/TRIGGER-COHERENCIA-CAPAS.md b/orchestration/_archive/directivas/TRIGGER-COHERENCIA-CAPAS.md similarity index 100% rename from orchestration/directivas/TRIGGER-COHERENCIA-CAPAS.md rename to orchestration/_archive/directivas/TRIGGER-COHERENCIA-CAPAS.md diff --git a/orchestration/directivas/TRIGGER-INVENTARIOS.md b/orchestration/_archive/directivas/TRIGGER-INVENTARIOS.md similarity index 100% rename from orchestration/directivas/TRIGGER-INVENTARIOS.md rename to orchestration/_archive/directivas/TRIGGER-INVENTARIOS.md diff --git a/orchestration/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md b/orchestration/_archive/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md similarity index 100% rename from orchestration/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md rename to orchestration/_archive/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md diff --git a/orchestration/directivas/principios/PRINCIPIO-CAPVED.md b/orchestration/_archive/directivas/principios/PRINCIPIO-CAPVED.md similarity index 100% rename from orchestration/directivas/principios/PRINCIPIO-CAPVED.md rename to orchestration/_archive/directivas/principios/PRINCIPIO-CAPVED.md diff --git a/orchestration/directivas/principios/PRINCIPIO-DOC-PRIMERO.md b/orchestration/_archive/directivas/principios/PRINCIPIO-DOC-PRIMERO.md similarity index 100% rename from orchestration/directivas/principios/PRINCIPIO-DOC-PRIMERO.md rename to orchestration/_archive/directivas/principios/PRINCIPIO-DOC-PRIMERO.md diff --git a/orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md b/orchestration/_archive/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md similarity index 100% rename from orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md rename to orchestration/_archive/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md diff --git a/orchestration/directivas/principios/PRINCIPIO-NO-ASUMIR.md b/orchestration/_archive/directivas/principios/PRINCIPIO-NO-ASUMIR.md similarity index 96% rename from orchestration/directivas/principios/PRINCIPIO-NO-ASUMIR.md rename to orchestration/_archive/directivas/principios/PRINCIPIO-NO-ASUMIR.md index 7def8f3..e418081 100644 --- a/orchestration/directivas/principios/PRINCIPIO-NO-ASUMIR.md +++ b/orchestration/_archive/directivas/principios/PRINCIPIO-NO-ASUMIR.md @@ -1,361 +1,361 @@ -# PRINCIPIO: NO ASUMIR - -**Version:** 1.0.0 -**Fecha:** 2025-12-12 -**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA -**Aplica a:** TODOS los agentes sin excepcion - ---- - -## DECLARACION DEL PRINCIPIO - -``` -╔══════════════════════════════════════════════════════════════════════╗ -║ ║ -║ "Si no esta documentado, NO asumir. PREGUNTAR." ║ -║ ║ -║ Nunca implementar basado en suposiciones. ║ -║ Nunca inventar requisitos. ║ -║ Nunca tomar decisiones de negocio sin autorizacion. ║ -║ ║ -╚══════════════════════════════════════════════════════════════════════╝ -``` - ---- - -## REGLA INQUEBRANTABLE - -``` -┌─────────────────────────────────────────────────────────────────────┐ -│ │ -│ PROHIBIDO: │ -│ - Asumir valores/comportamientos no documentados │ -│ - Inventar requisitos o especificaciones │ -│ - Tomar decisiones de negocio sin consultar │ -│ - Implementar "lo que parece logico" sin confirmacion │ -│ - Interpretar ambiguedad a favor de una opcion │ -│ - Completar huecos de documentacion con suposiciones │ -│ │ -│ OBLIGATORIO: │ -│ - Detener trabajo cuando falta informacion critica │ -│ - Documentar la pregunta claramente │ -│ - Escalar al Product Owner │ -│ - Esperar respuesta antes de continuar │ -│ - Documentar la decision antes de implementar │ -│ │ -└─────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## POR QUE ESTE PRINCIPIO - -```yaml -problema: - - Implementaciones basadas en suposiciones causan retrabajo - - Asunciones incorrectas generan bugs de negocio - - Decisiones no autorizadas crean deuda tecnica - - Interpretaciones personales divergen del objetivo real - -consecuencias_de_asumir: - - Codigo que no cumple requisitos reales - - Retrabajo costoso cuando se descubre la asuncion incorrecta - - Perdida de confianza del cliente/PO - - Documentacion desalineada con implementacion - - Bugs dificiles de rastrear (parecen funcionar pero no son correctos) - -beneficios_de_preguntar: - - Implementacion correcta desde el inicio - - Documentacion completa y precisa - - Menos retrabajo - - Mayor confianza del equipo - - Decisiones respaldadas por autoridad correcta -``` - ---- - -## CUANDO APLICA ESTE PRINCIPIO - -### Casos que REQUIEREN Escalamiento - -```yaml -informacion_faltante: - - Tabla mencionada sin definicion de columnas - - Endpoint sin especificacion de payload - - Pagina sin definicion de componentes - - Regla de negocio incompleta - - Valores de enum no especificados - - Validaciones no documentadas - - Comportamiento de error no definido - - Limites/umbrales no especificados - -ambiguedad: - - Requisito interpretable de multiples formas - - Contradiccion entre documentos - - Alcance no claramente definido - - Criterios de aceptacion vagos - - Casos edge no cubiertos - -decisiones_de_negocio: - - Cambio que afecta UX - - Modificacion de flujos existentes - - Nuevas restricciones - - Priorizacion entre alternativas - - Trade-offs con impacto en usuario -``` - -### Casos que NO Requieren Escalamiento - -```yaml -decisiones_tecnicas_puras: - - Nombre de variable interna - - Estructura de codigo (si no afecta API) - - Optimizaciones de rendimiento - - Refactorizaciones internas - → Consultar Architecture-Analyst si hay duda - -implementacion_clara: - - Documentacion existe y es clara - - No hay ambiguedad - - Comportamiento esta especificado - → Proceder con implementacion - -estandares_definidos: - - Nomenclatura definida en directivas - - Patrones definidos en SIMCO - - Convenciones del proyecto - → Seguir lo establecido -``` - ---- - -## COMO APLICAR ESTE PRINCIPIO - -### Paso 1: Buscar Exhaustivamente - -```yaml -ANTES_de_escalar: - buscar_en: - - docs/01-requerimientos/ - - docs/02-especificaciones-tecnicas/ - - docs/97-adr/ - - orchestration/inventarios/ - - Codigo existente relacionado - - Historial de trazas - - tiempo_minimo: "10-15 minutos de busqueda activa" -``` - -### Paso 2: Si No se Encuentra, Documentar - -```markdown -## INFORMACION NO ENCONTRADA - -**Busqueda realizada:** -- [X] docs/01-requerimientos/ - No encontrado -- [X] docs/02-especificaciones-tecnicas/ - Mencionado pero incompleto -- [X] ADRs - No hay ADR relacionado -- [X] Inventarios - N/A - -**Conclusion:** Informacion no disponible, requiere escalamiento -``` - -### Paso 3: Escalar Correctamente - -```markdown -## CONSULTA AL PRODUCT OWNER - -**Fecha:** {fecha} -**Agente:** {agente} -**Tarea:** [{ID}] {titulo} - -### Contexto -{que estoy haciendo} - -### Lo que encontre -{informacion parcial disponible} - -### Lo que falta / es ambiguo -{descripcion clara del gap} - -### Pregunta especifica -{pregunta concreta} - -### Opciones (si las identifique) -1. {opcion A} -2. {opcion B} - -### Impacto -{que pasa si no se resuelve} -``` - -### Paso 4: Esperar y Documentar Respuesta - -```yaml -MIENTRAS_espero: - - NO implementar esa parte - - Continuar con otras tareas si es posible - - Marcar tarea como BLOQUEADA si es critico - -CUANDO_recibo_respuesta: - - Documentar la decision - - Actualizar documentacion correspondiente - - Crear ADR si es decision significativa - - Continuar implementacion -``` - ---- - -## FLUJO DE DECISION - -``` -┌─────────────────────────────────────┐ -│ Encontrar informacion faltante │ -│ o ambiguedad │ -└──────────────┬──────────────────────┘ - │ - ▼ -┌─────────────────────────────────────┐ -│ Buscar exhaustivamente en docs │ -│ (10-15 minutos minimo) │ -└──────────────┬──────────────────────┘ - │ - ▼ - ┌──────┴──────┐ - │ Encontrado? │ - └──────┬──────┘ - │ - ┌────────┴────────┐ - │ SI │ NO - ▼ ▼ -┌───────────┐ ┌─────────────────────┐ -│ Proceder │ │ DETENER │ -│ con │ │ Documentar pregunta │ -│ implement │ │ Escalar al PO │ -└───────────┘ └──────────┬──────────┘ - │ - ▼ - ┌─────────────────────┐ - │ ESPERAR respuesta │ - │ (NO asumir) │ - └──────────┬──────────┘ - │ - ▼ - ┌─────────────────────┐ - │ Documentar decision │ - │ Continuar │ - └─────────────────────┘ -``` - ---- - -## EJEMPLOS - -### Ejemplo CORRECTO - -```yaml -situacion: "DDL menciona campo 'status' pero no especifica valores" - -proceso_correcto: - 1. Buscar en docs/: No encontrado - 2. Buscar en specs: Solo dice "tiene status" - 3. Buscar en ADRs: No hay ADR - 4. Conclusion: Escalar - 5. Documentar: "Cuales son los valores validos de status?" - 6. Esperar respuesta - 7. PO responde: "['draft', 'active', 'completed']" - 8. Documentar decision - 9. Implementar con valores correctos -``` - -### Ejemplo INCORRECTO - -```yaml -situacion: "DDL menciona campo 'status' pero no especifica valores" - -proceso_incorrecto: - 1. "Parece que deberian ser 'pending', 'done'" - 2. Implementar con esos valores - 3. PO revisa y dice: "No, son 'draft', 'active', 'completed'" - 4. Retrabajo: migration, seed update, tests, backend, frontend - 5. Tiempo perdido: 2-4 horas -``` - ---- - -## CONSECUENCIAS DE IGNORAR - -```yaml -ignorar_este_principio: - retrabajo: - - Implementacion incorrecta debe rehacerse - - Tests basados en asuncion incorrecta - - Documentacion desalineada - - bugs_de_negocio: - - Funcionalidad no cumple expectativas - - Comportamiento inesperado para usuarios - - Datos incorrectos en sistema - - deuda_tecnica: - - Codigo parche sobre asuncion incorrecta - - Inconsistencias acumuladas - - Complejidad innecesaria - - perdida_de_confianza: - - PO pierde confianza en implementaciones - - Mas revision necesaria - - Ciclos de feedback mas largos -``` - ---- - -## CHECKLIST RAPIDO - -``` -Antes de implementar algo no 100% claro: - -[ ] Busque en documentacion? (10-15 min minimo) -[ ] Revise specs, ADRs, inventarios? -[ ] Sigue sin estar claro? -[ ] Documente la pregunta? -[ ] Escale al PO? -[ ] Espere respuesta? -[ ] Documente la decision? -[ ] Actualice documentacion correspondiente? - -Solo entonces: Proceder con implementacion -``` - ---- - -## RELACION CON OTROS PRINCIPIOS - -```yaml -PRINCIPIO-DOC-PRIMERO: - - Leer docs antes de implementar - - Si docs estan incompletos -> NO-ASUMIR aplica - -PRINCIPIO-CAPVED: - - Fase A (Analisis): Identificar informacion faltante - - Fase V (Validacion): NO aprobar sin informacion completa - -PRINCIPIO-VALIDACION-OBLIGATORIA: - - Validar que implementacion coincide con decision documentada -``` - ---- - -## REFERENCIAS SIMCO - -- **@ESCALAMIENTO** - Proceso completo de escalamiento -- **@DOC_PRIMERO** - Consultar documentacion primero -- **@TAREA** - Ciclo de vida de tareas - ---- - -**Este principio es OBLIGATORIO y NO puede ser ignorado por ningun agente.** - ---- - -**Version:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental +# PRINCIPIO: NO ASUMIR + +**Version:** 1.0.0 +**Fecha:** 2025-12-12 +**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA +**Aplica a:** TODOS los agentes sin excepcion + +--- + +## DECLARACION DEL PRINCIPIO + +``` +╔══════════════════════════════════════════════════════════════════════╗ +║ ║ +║ "Si no esta documentado, NO asumir. PREGUNTAR." ║ +║ ║ +║ Nunca implementar basado en suposiciones. ║ +║ Nunca inventar requisitos. ║ +║ Nunca tomar decisiones de negocio sin autorizacion. ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## REGLA INQUEBRANTABLE + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ │ +│ PROHIBIDO: │ +│ - Asumir valores/comportamientos no documentados │ +│ - Inventar requisitos o especificaciones │ +│ - Tomar decisiones de negocio sin consultar │ +│ - Implementar "lo que parece logico" sin confirmacion │ +│ - Interpretar ambiguedad a favor de una opcion │ +│ - Completar huecos de documentacion con suposiciones │ +│ │ +│ OBLIGATORIO: │ +│ - Detener trabajo cuando falta informacion critica │ +│ - Documentar la pregunta claramente │ +│ - Escalar al Product Owner │ +│ - Esperar respuesta antes de continuar │ +│ - Documentar la decision antes de implementar │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## POR QUE ESTE PRINCIPIO + +```yaml +problema: + - Implementaciones basadas en suposiciones causan retrabajo + - Asunciones incorrectas generan bugs de negocio + - Decisiones no autorizadas crean deuda tecnica + - Interpretaciones personales divergen del objetivo real + +consecuencias_de_asumir: + - Codigo que no cumple requisitos reales + - Retrabajo costoso cuando se descubre la asuncion incorrecta + - Perdida de confianza del cliente/PO + - Documentacion desalineada con implementacion + - Bugs dificiles de rastrear (parecen funcionar pero no son correctos) + +beneficios_de_preguntar: + - Implementacion correcta desde el inicio + - Documentacion completa y precisa + - Menos retrabajo + - Mayor confianza del equipo + - Decisiones respaldadas por autoridad correcta +``` + +--- + +## CUANDO APLICA ESTE PRINCIPIO + +### Casos que REQUIEREN Escalamiento + +```yaml +informacion_faltante: + - Tabla mencionada sin definicion de columnas + - Endpoint sin especificacion de payload + - Pagina sin definicion de componentes + - Regla de negocio incompleta + - Valores de enum no especificados + - Validaciones no documentadas + - Comportamiento de error no definido + - Limites/umbrales no especificados + +ambiguedad: + - Requisito interpretable de multiples formas + - Contradiccion entre documentos + - Alcance no claramente definido + - Criterios de aceptacion vagos + - Casos edge no cubiertos + +decisiones_de_negocio: + - Cambio que afecta UX + - Modificacion de flujos existentes + - Nuevas restricciones + - Priorizacion entre alternativas + - Trade-offs con impacto en usuario +``` + +### Casos que NO Requieren Escalamiento + +```yaml +decisiones_tecnicas_puras: + - Nombre de variable interna + - Estructura de codigo (si no afecta API) + - Optimizaciones de rendimiento + - Refactorizaciones internas + → Consultar Architecture-Analyst si hay duda + +implementacion_clara: + - Documentacion existe y es clara + - No hay ambiguedad + - Comportamiento esta especificado + → Proceder con implementacion + +estandares_definidos: + - Nomenclatura definida en directivas + - Patrones definidos en SIMCO + - Convenciones del proyecto + → Seguir lo establecido +``` + +--- + +## COMO APLICAR ESTE PRINCIPIO + +### Paso 1: Buscar Exhaustivamente + +```yaml +ANTES_de_escalar: + buscar_en: + - docs/01-requerimientos/ + - docs/02-especificaciones-tecnicas/ + - docs/97-adr/ + - orchestration/inventarios/ + - Codigo existente relacionado + - Historial de trazas + + tiempo_minimo: "10-15 minutos de busqueda activa" +``` + +### Paso 2: Si No se Encuentra, Documentar + +```markdown +## INFORMACION NO ENCONTRADA + +**Busqueda realizada:** +- [X] docs/01-requerimientos/ - No encontrado +- [X] docs/02-especificaciones-tecnicas/ - Mencionado pero incompleto +- [X] ADRs - No hay ADR relacionado +- [X] Inventarios - N/A + +**Conclusion:** Informacion no disponible, requiere escalamiento +``` + +### Paso 3: Escalar Correctamente + +```markdown +## CONSULTA AL PRODUCT OWNER + +**Fecha:** {fecha} +**Agente:** {agente} +**Tarea:** [{ID}] {titulo} + +### Contexto +{que estoy haciendo} + +### Lo que encontre +{informacion parcial disponible} + +### Lo que falta / es ambiguo +{descripcion clara del gap} + +### Pregunta especifica +{pregunta concreta} + +### Opciones (si las identifique) +1. {opcion A} +2. {opcion B} + +### Impacto +{que pasa si no se resuelve} +``` + +### Paso 4: Esperar y Documentar Respuesta + +```yaml +MIENTRAS_espero: + - NO implementar esa parte + - Continuar con otras tareas si es posible + - Marcar tarea como BLOQUEADA si es critico + +CUANDO_recibo_respuesta: + - Documentar la decision + - Actualizar documentacion correspondiente + - Crear ADR si es decision significativa + - Continuar implementacion +``` + +--- + +## FLUJO DE DECISION + +``` +┌─────────────────────────────────────┐ +│ Encontrar informacion faltante │ +│ o ambiguedad │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Buscar exhaustivamente en docs │ +│ (10-15 minutos minimo) │ +└──────────────┬──────────────────────┘ + │ + ▼ + ┌──────┴──────┐ + │ Encontrado? │ + └──────┬──────┘ + │ + ┌────────┴────────┐ + │ SI │ NO + ▼ ▼ +┌───────────┐ ┌─────────────────────┐ +│ Proceder │ │ DETENER │ +│ con │ │ Documentar pregunta │ +│ implement │ │ Escalar al PO │ +└───────────┘ └──────────┬──────────┘ + │ + ▼ + ┌─────────────────────┐ + │ ESPERAR respuesta │ + │ (NO asumir) │ + └──────────┬──────────┘ + │ + ▼ + ┌─────────────────────┐ + │ Documentar decision │ + │ Continuar │ + └─────────────────────┘ +``` + +--- + +## EJEMPLOS + +### Ejemplo CORRECTO + +```yaml +situacion: "DDL menciona campo 'status' pero no especifica valores" + +proceso_correcto: + 1. Buscar en docs/: No encontrado + 2. Buscar en specs: Solo dice "tiene status" + 3. Buscar en ADRs: No hay ADR + 4. Conclusion: Escalar + 5. Documentar: "Cuales son los valores validos de status?" + 6. Esperar respuesta + 7. PO responde: "['draft', 'active', 'completed']" + 8. Documentar decision + 9. Implementar con valores correctos +``` + +### Ejemplo INCORRECTO + +```yaml +situacion: "DDL menciona campo 'status' pero no especifica valores" + +proceso_incorrecto: + 1. "Parece que deberian ser 'pending', 'done'" + 2. Implementar con esos valores + 3. PO revisa y dice: "No, son 'draft', 'active', 'completed'" + 4. Retrabajo: migration, seed update, tests, backend, frontend + 5. Tiempo perdido: 2-4 horas +``` + +--- + +## CONSECUENCIAS DE IGNORAR + +```yaml +ignorar_este_principio: + retrabajo: + - Implementacion incorrecta debe rehacerse + - Tests basados en asuncion incorrecta + - Documentacion desalineada + + bugs_de_negocio: + - Funcionalidad no cumple expectativas + - Comportamiento inesperado para usuarios + - Datos incorrectos en sistema + + deuda_tecnica: + - Codigo parche sobre asuncion incorrecta + - Inconsistencias acumuladas + - Complejidad innecesaria + + perdida_de_confianza: + - PO pierde confianza en implementaciones + - Mas revision necesaria + - Ciclos de feedback mas largos +``` + +--- + +## CHECKLIST RAPIDO + +``` +Antes de implementar algo no 100% claro: + +[ ] Busque en documentacion? (10-15 min minimo) +[ ] Revise specs, ADRs, inventarios? +[ ] Sigue sin estar claro? +[ ] Documente la pregunta? +[ ] Escale al PO? +[ ] Espere respuesta? +[ ] Documente la decision? +[ ] Actualice documentacion correspondiente? + +Solo entonces: Proceder con implementacion +``` + +--- + +## RELACION CON OTROS PRINCIPIOS + +```yaml +PRINCIPIO-DOC-PRIMERO: + - Leer docs antes de implementar + - Si docs estan incompletos -> NO-ASUMIR aplica + +PRINCIPIO-CAPVED: + - Fase A (Analisis): Identificar informacion faltante + - Fase V (Validacion): NO aprobar sin informacion completa + +PRINCIPIO-VALIDACION-OBLIGATORIA: + - Validar que implementacion coincide con decision documentada +``` + +--- + +## REFERENCIAS SIMCO + +- **@ESCALAMIENTO** - Proceso completo de escalamiento +- **@DOC_PRIMERO** - Consultar documentacion primero +- **@TAREA** - Ciclo de vida de tareas + +--- + +**Este principio es OBLIGATORIO y NO puede ser ignorado por ningun agente.** + +--- + +**Version:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental diff --git a/orchestration/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md b/orchestration/_archive/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md similarity index 100% rename from orchestration/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md rename to orchestration/_archive/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md diff --git a/orchestration/directivas/principios/PROPAGACION-ARCHITECTURE.md b/orchestration/_archive/directivas/principios/PROPAGACION-ARCHITECTURE.md similarity index 100% rename from orchestration/directivas/principios/PROPAGACION-ARCHITECTURE.md rename to orchestration/_archive/directivas/principios/PROPAGACION-ARCHITECTURE.md diff --git a/orchestration/directivas/simco/SIMCO-GIT.md b/orchestration/_archive/directivas/simco/SIMCO-GIT.md similarity index 96% rename from orchestration/directivas/simco/SIMCO-GIT.md rename to orchestration/_archive/directivas/simco/SIMCO-GIT.md index faec47b..a8b049f 100644 --- a/orchestration/directivas/simco/SIMCO-GIT.md +++ b/orchestration/_archive/directivas/simco/SIMCO-GIT.md @@ -1,510 +1,510 @@ -# SIMCO: GIT (Control de Versiones) - -**Version:** 1.2.0 -**Fecha:** 2026-01-16 -**Aplica a:** TODO agente que modifica codigo o documentacion -**Prioridad:** OBLIGATORIA - ---- - -## RESUMEN EJECUTIVO - -> **Todo cambio en codigo o documentacion DEBE versionarse correctamente.** -> **Commits frecuentes, atomicos y descriptivos.** -> **PUSH OBLIGATORIO al finalizar cada tarea.** -> **FETCH OBLIGATORIO antes de verificar estado.** -> **Nunca perder trabajo por falta de commits o push.** - ---- - -## REGLA CRITICA 1: FETCH ANTES DE OPERAR - -``` -╔══════════════════════════════════════════════════════════════════════════╗ -║ ║ -║ ANTES DE CUALQUIER VERIFICACION DE ESTADO GIT: ║ -║ ║ -║ 1. git fetch origin ║ -║ → Obtener estado actual del remoto ║ -║ ║ -║ 2. git log HEAD..origin/main --oneline ║ -║ → Si hay output = hay commits remotos que no tienes ║ -║ ║ -║ 3. Si hay commits remotos: ║ -║ git pull --no-recurse-submodules ║ -║ → Sincronizar antes de continuar ║ -║ ║ -║ 4. AHORA SI: git status ║ -║ → Verificar estado local ║ -║ ║ -║ SIN FETCH = ESTADO INCOMPLETO ║ -║ (Otro agente pudo hacer cambios en otra sesion) ║ -║ ║ -║ Referencia: INC-2026-01-16-001 ║ -║ ║ -╚══════════════════════════════════════════════════════════════════════════╝ -``` - -### Secuencia Obligatoria de Verificacion - -```bash -# SIEMPRE ejecutar en este orden: -git fetch origin -git log HEAD..origin/main --oneline # Si hay output, hacer pull -git pull --no-recurse-submodules # Solo si paso anterior tiene output -git status # Ahora si verificar estado local -``` - ---- - -## REGLA CRITICA 2: COMMIT + PUSH OBLIGATORIO - -``` -╔══════════════════════════════════════════════════════════════════════════╗ -║ ║ -║ TODA TAREA QUE CREA O MODIFICA ARCHIVOS DEBE TERMINAR CON: ║ -║ ║ -║ 1. git add . ║ -║ 2. git commit -m "[ID] tipo: descripcion" ║ -║ 3. git push origin {rama} ║ -║ ║ -║ SIN PUSH = TAREA INCOMPLETA ║ -║ ║ -║ En workspace con SUBMODULES: ║ -║ - Commitear y push en CADA submodule afectado ║ -║ - Luego commitear y push en workspace principal ║ -║ ║ -╚══════════════════════════════════════════════════════════════════════════╝ -``` - -### Checklist Fin de Tarea (OBLIGATORIO) - -```yaml -ANTES_de_reportar_tarea_completada: - - [ ] Todos los archivos creados/modificados estan guardados - - [ ] git status muestra archivos a commitear - - [ ] git add {archivos} - - [ ] git commit -m "[TAREA-ID] tipo: descripcion" - - [ ] git push origin {rama} - - [ ] Verificar: git status muestra "nothing to commit, working tree clean" - - [ ] Verificar: git log origin/main..HEAD muestra vacio (todo pusheado) - -SI_hay_SUBMODULES: - - [ ] Repetir proceso en CADA submodule modificado - - [ ] Luego actualizar referencias en workspace principal - - [ ] Push final del workspace principal -``` - -### Secuencia para Workspace con Submodules - -```bash -# 1. Commitear en cada submodule modificado -cd projects/{submodule} -git add . -git commit -m "[TAREA-ID] tipo: descripcion" -git push origin main - -# 2. Repetir para cada submodule afectado -# ... - -# 3. Actualizar workspace principal -cd /home/isem/workspace-v2 -git add projects/{submodule} # Actualiza referencia del submodule -git commit -m "[WORKSPACE] chore: Update submodule references" -git push origin main - -# 4. Verificar todo sincronizado -git status # Debe mostrar "clean" -``` - ---- - -## PRINCIPIOS FUNDAMENTALES - -``` -╔══════════════════════════════════════════════════════════════════════╗ -║ ║ -║ "Commitear temprano, commitear frecuentemente" ║ -║ ║ -║ Cada commit debe: ║ -║ - Representar un cambio logico completo ║ -║ - Ser funcional (no romper compilacion) ║ -║ - Ser reversible sin afectar otros cambios ║ -║ - Tener mensaje descriptivo con ID de tarea ║ -║ ║ -╚══════════════════════════════════════════════════════════════════════╝ -``` - ---- - -## FRECUENCIA DE COMMITS - -```yaml -OBLIGATORIO_commitear: - - Al finalizar cada fase (Analisis, Planeacion, Ejecucion) - - Al completar cada archivo significativo - - Cada 30-45 minutos de trabajo continuo - - Antes de lanzar subagentes - - Despues de validar trabajo de subagentes - - Antes de cambiar de tarea - - Cuando build + lint pasan - -RAZON: "Minimizar perdida de trabajo en caso de error" -``` - ---- - -## FORMATO DE MENSAJE DE COMMIT - -### Estructura Obligatoria - -``` -[{TAREA-ID}] {tipo}: {descripcion concisa} - -{cuerpo opcional - descripcion detallada} - -{footer opcional - referencias, breaking changes} -``` - -### Ejemplos Correctos - -```bash -# Feature nueva -[DB-042] feat: Crear tabla projects con soporte PostGIS - -# Bug fix -[BE-015] fix: Corregir validacion de codigo unico en ProjectService - -# Refactor -[FE-008] refactor: Extraer componente ProjectCard de ProjectList - -# Documentacion -[DB-042] docs: Actualizar DATABASE_INVENTORY con tabla projects - -# Tests -[BE-015] test: Agregar tests unitarios para ProjectService - -# Subtarea -[DB-042-SUB-001] feat: Implementar indices para tabla projects -``` - -### Ejemplos Incorrectos - -```bash -# Sin ID de tarea -fix: Corregir bug - -# Muy vago -[BE-015] update: Cambios varios - -# Demasiado largo en primera linea -[DB-042] feat: Crear tabla projects con todas las columnas necesarias incluyendo soporte para PostGIS y configuracion de indices compuestos para optimizar queries - -# Sin tipo -[FE-008] Mejorar componente -``` - ---- - -## TIPOS DE COMMITS - -| Tipo | Uso | Ejemplo | -|------|-----|---------| -| `feat` | Nueva funcionalidad | `[DB-042] feat: Agregar soporte PostGIS` | -| `fix` | Correccion de bug | `[BE-015] fix: Resolver error en constraint` | -| `refactor` | Refactorizacion sin cambio funcional | `[FE-008] refactor: Mejorar estructura componentes` | -| `docs` | Solo documentacion | `[DB-042] docs: Actualizar README con schema` | -| `test` | Agregar/modificar tests | `[BE-015] test: Agregar tests para ProjectService` | -| `chore` | Tareas de mantenimiento | `[DB-042] chore: Actualizar dependencias` | -| `style` | Formato/estilo (sin cambio logico) | `[FE-008] style: Aplicar prettier` | -| `perf` | Mejora de performance | `[DB-042] perf: Agregar indice compuesto` | -| `build` | Cambios en build/deps | `[BE-015] build: Actualizar TypeORM a v0.3` | -| `ci` | Cambios en CI/CD | `[INFRA-001] ci: Agregar workflow de tests` | - ---- - -## COMMITS ATOMICOS - -### Que es un Commit Atomico - -```yaml -atomico: - - Representa UN cambio logico completo - - Es funcional (build pasa) - - Es reversible individualmente - - No mezcla cambios no relacionados - -NO_atomico: - - Multiples cambios no relacionados - - Trabajo incompleto (excepto WIP explicito) - - Mezcla de fix y feat - - Cambios en multiples features -``` - -### Ejemplo de Atomicidad - -```bash -# CORRECTO - Commits atomicos separados -[DB-042] feat: Crear tabla projects -[DB-042] feat: Agregar indices a tabla projects -[DB-042] feat: Crear seeds para projects -[DB-042] docs: Actualizar inventario con tabla projects - -# INCORRECTO - Un commit masivo -[DB-042] feat: Crear tabla projects con indices, seeds y actualizacion de inventario -``` - ---- - -## FLUJO DE TRABAJO GIT - -### Antes de Empezar Tarea - -```bash -# 1. Asegurar rama actualizada -git fetch origin -git pull origin main - -# 2. Crear rama de trabajo (si aplica) -git checkout -b feature/{TAREA-ID}-descripcion-corta - -# 3. Verificar estado limpio -git status -``` - -### Durante la Tarea - -```bash -# 1. Hacer cambios -# ... editar archivos ... - -# 2. Verificar que build pasa -npm run build -npm run lint - -# 3. Agregar cambios -git add {archivos especificos} -# o para todos los cambios relacionados: -git add . - -# 4. Commit con mensaje descriptivo -git commit -m "[TAREA-ID] tipo: descripcion" - -# 5. Repetir para cada cambio logico -``` - -### Al Completar Tarea - -```bash -# 1. Verificar historial -git log --oneline -5 - -# 2. Push a remoto -git push origin {rama} - -# 3. Crear PR si aplica -gh pr create --title "[TAREA-ID] Descripcion" --body "..." -``` - ---- - -## CHECKLIST PRE-COMMIT - -```yaml -ANTES_de_cada_commit: - - [ ] Build pasa sin errores - - [ ] Lint pasa sin errores criticos - - [ ] Tests pasan (si existen) - - [ ] Cambios son logicamente completos - - [ ] No hay archivos no deseados (node_modules, .env, etc.) - - [ ] Mensaje sigue formato correcto - -VERIFICAR: - git status # Ver archivos modificados - git diff # Ver cambios en detalle - git diff --cached # Ver cambios staged -``` - ---- - -## ERRORES COMUNES - -| Error | Consecuencia | Solucion | -|-------|--------------|----------| -| No commitear frecuentemente | Perdida de trabajo | Commit cada 30-45 min | -| Commits masivos | Dificil revertir | Commits atomicos | -| Mensajes vagos | Historial incomprensible | Seguir formato | -| Commit con build roto | Bloquea CI/CD | Verificar antes de commit | -| Olvidar ID de tarea | Perdida de trazabilidad | Siempre incluir [TAREA-ID] | -| Commitear secretos | Brecha de seguridad | Verificar .gitignore | - ---- - -## ARCHIVOS A IGNORAR (.gitignore) - -```yaml -SIEMPRE_ignorar: - - node_modules/ - - .env - - .env.* - - dist/ - - build/ - - coverage/ - - *.log - - .DS_Store - - *.tmp - - *.cache - -NUNCA_commitear: - - Credenciales - - API keys - - Passwords - - Certificados privados - - Archivos de configuracion local -``` - ---- - -## RAMAS (BRANCHING) - -### Convencion de Nombres - -```yaml -ramas: - feature: feature/{TAREA-ID}-descripcion-corta - bugfix: bugfix/{TAREA-ID}-descripcion-corta - hotfix: hotfix/{TAREA-ID}-descripcion-corta - release: release/v{X.Y.Z} - -ejemplos: - - feature/DB-042-crear-tabla-projects - - bugfix/BE-015-fix-validacion - - hotfix/SEC-001-fix-xss - - release/v2.1.0 -``` - -### Flujo de Ramas - -``` -main (produccion) - │ - ├─── develop (desarrollo) - │ │ - │ ├─── feature/DB-042-* - │ │ └── merge a develop - │ │ - │ ├─── feature/BE-015-* - │ │ └── merge a develop - │ │ - │ └── release/v2.1.0 - │ └── merge a main + tag - │ - └─── hotfix/SEC-001-* - └── merge a main + develop -``` - ---- - -## REVERTIR CAMBIOS - -### Revertir Ultimo Commit (no pusheado) - -```bash -# Mantener cambios en working directory -git reset --soft HEAD~1 - -# Descartar cambios completamente -git reset --hard HEAD~1 -``` - -### Revertir Commit ya Pusheado - -```bash -# Crear commit de reversion (seguro) -git revert {commit-hash} -git push -``` - -### Deshacer Cambios en Archivo - -```bash -# Descartar cambios no staged -git checkout -- {archivo} - -# Descartar cambios staged -git reset HEAD {archivo} -git checkout -- {archivo} -``` - ---- - -## SITUACIONES ESPECIALES - -### Work in Progress (WIP) - -```bash -# Cuando necesitas commitear trabajo incompleto -git commit -m "[TAREA-ID] WIP: descripcion de estado actual" - -# Luego, completar y hacer commit final -# (opcional: squash commits WIP antes de PR) -``` - -### Antes de Lanzar Subagente - -```bash -# SIEMPRE commitear antes de delegar -git add . -git commit -m "[TAREA-ID] chore: Estado antes de delegacion a {SubAgente}" -``` - -### Despues de Validar Subagente - -```bash -# Commitear resultado de subagente -git add . -git commit -m "[TAREA-ID-SUB-XXX] tipo: Resultado de {SubAgente}" -``` - ---- - -## VALIDACION DE COMMITS - -### Verificar Historial - -```bash -# Ver ultimos commits -git log --oneline -10 - -# Ver commits de tarea especifica -git log --oneline --grep="DB-042" - -# Ver cambios de un commit -git show {commit-hash} -``` - -### Verificar Formato de Mensaje - -```yaml -formato_valido: - - Tiene [TAREA-ID] al inicio - - Tiene tipo valido (feat, fix, etc.) - - Descripcion concisa (<72 caracteres primera linea) - - No tiene errores de ortografia graves - -verificar_manualmente: - git log --oneline -1 - # Debe mostrar: {hash} [TAREA-ID] tipo: descripcion -``` - ---- - -## REFERENCIAS - -- **Principio de Validacion:** @PRINCIPIOS/PRINCIPIO-VALIDACION-OBLIGATORIA.md -- **Documentar:** @SIMCO/SIMCO-DOCUMENTAR.md -- **Crear:** @SIMCO/SIMCO-CREAR.md - ---- - -**Version:** 1.0.0 | **Sistema:** SIMCO | **Mantenido por:** Tech Lead +# SIMCO: GIT (Control de Versiones) + +**Version:** 1.2.0 +**Fecha:** 2026-01-16 +**Aplica a:** TODO agente que modifica codigo o documentacion +**Prioridad:** OBLIGATORIA + +--- + +## RESUMEN EJECUTIVO + +> **Todo cambio en codigo o documentacion DEBE versionarse correctamente.** +> **Commits frecuentes, atomicos y descriptivos.** +> **PUSH OBLIGATORIO al finalizar cada tarea.** +> **FETCH OBLIGATORIO antes de verificar estado.** +> **Nunca perder trabajo por falta de commits o push.** + +--- + +## REGLA CRITICA 1: FETCH ANTES DE OPERAR + +``` +╔══════════════════════════════════════════════════════════════════════════╗ +║ ║ +║ ANTES DE CUALQUIER VERIFICACION DE ESTADO GIT: ║ +║ ║ +║ 1. git fetch origin ║ +║ → Obtener estado actual del remoto ║ +║ ║ +║ 2. git log HEAD..origin/main --oneline ║ +║ → Si hay output = hay commits remotos que no tienes ║ +║ ║ +║ 3. Si hay commits remotos: ║ +║ git pull --no-recurse-submodules ║ +║ → Sincronizar antes de continuar ║ +║ ║ +║ 4. AHORA SI: git status ║ +║ → Verificar estado local ║ +║ ║ +║ SIN FETCH = ESTADO INCOMPLETO ║ +║ (Otro agente pudo hacer cambios en otra sesion) ║ +║ ║ +║ Referencia: INC-2026-01-16-001 ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════════╝ +``` + +### Secuencia Obligatoria de Verificacion + +```bash +# SIEMPRE ejecutar en este orden: +git fetch origin +git log HEAD..origin/main --oneline # Si hay output, hacer pull +git pull --no-recurse-submodules # Solo si paso anterior tiene output +git status # Ahora si verificar estado local +``` + +--- + +## REGLA CRITICA 2: COMMIT + PUSH OBLIGATORIO + +``` +╔══════════════════════════════════════════════════════════════════════════╗ +║ ║ +║ TODA TAREA QUE CREA O MODIFICA ARCHIVOS DEBE TERMINAR CON: ║ +║ ║ +║ 1. git add . ║ +║ 2. git commit -m "[ID] tipo: descripcion" ║ +║ 3. git push origin {rama} ║ +║ ║ +║ SIN PUSH = TAREA INCOMPLETA ║ +║ ║ +║ En workspace con SUBMODULES: ║ +║ - Commitear y push en CADA submodule afectado ║ +║ - Luego commitear y push en workspace principal ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════════╝ +``` + +### Checklist Fin de Tarea (OBLIGATORIO) + +```yaml +ANTES_de_reportar_tarea_completada: + - [ ] Todos los archivos creados/modificados estan guardados + - [ ] git status muestra archivos a commitear + - [ ] git add {archivos} + - [ ] git commit -m "[TAREA-ID] tipo: descripcion" + - [ ] git push origin {rama} + - [ ] Verificar: git status muestra "nothing to commit, working tree clean" + - [ ] Verificar: git log origin/main..HEAD muestra vacio (todo pusheado) + +SI_hay_SUBMODULES: + - [ ] Repetir proceso en CADA submodule modificado + - [ ] Luego actualizar referencias en workspace principal + - [ ] Push final del workspace principal +``` + +### Secuencia para Workspace con Submodules + +```bash +# 1. Commitear en cada submodule modificado +cd projects/{submodule} +git add . +git commit -m "[TAREA-ID] tipo: descripcion" +git push origin main + +# 2. Repetir para cada submodule afectado +# ... + +# 3. Actualizar workspace principal +cd /home/isem/workspace-v2 +git add projects/{submodule} # Actualiza referencia del submodule +git commit -m "[WORKSPACE] chore: Update submodule references" +git push origin main + +# 4. Verificar todo sincronizado +git status # Debe mostrar "clean" +``` + +--- + +## PRINCIPIOS FUNDAMENTALES + +``` +╔══════════════════════════════════════════════════════════════════════╗ +║ ║ +║ "Commitear temprano, commitear frecuentemente" ║ +║ ║ +║ Cada commit debe: ║ +║ - Representar un cambio logico completo ║ +║ - Ser funcional (no romper compilacion) ║ +║ - Ser reversible sin afectar otros cambios ║ +║ - Tener mensaje descriptivo con ID de tarea ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## FRECUENCIA DE COMMITS + +```yaml +OBLIGATORIO_commitear: + - Al finalizar cada fase (Analisis, Planeacion, Ejecucion) + - Al completar cada archivo significativo + - Cada 30-45 minutos de trabajo continuo + - Antes de lanzar subagentes + - Despues de validar trabajo de subagentes + - Antes de cambiar de tarea + - Cuando build + lint pasan + +RAZON: "Minimizar perdida de trabajo en caso de error" +``` + +--- + +## FORMATO DE MENSAJE DE COMMIT + +### Estructura Obligatoria + +``` +[{TAREA-ID}] {tipo}: {descripcion concisa} + +{cuerpo opcional - descripcion detallada} + +{footer opcional - referencias, breaking changes} +``` + +### Ejemplos Correctos + +```bash +# Feature nueva +[DB-042] feat: Crear tabla projects con soporte PostGIS + +# Bug fix +[BE-015] fix: Corregir validacion de codigo unico en ProjectService + +# Refactor +[FE-008] refactor: Extraer componente ProjectCard de ProjectList + +# Documentacion +[DB-042] docs: Actualizar DATABASE_INVENTORY con tabla projects + +# Tests +[BE-015] test: Agregar tests unitarios para ProjectService + +# Subtarea +[DB-042-SUB-001] feat: Implementar indices para tabla projects +``` + +### Ejemplos Incorrectos + +```bash +# Sin ID de tarea +fix: Corregir bug + +# Muy vago +[BE-015] update: Cambios varios + +# Demasiado largo en primera linea +[DB-042] feat: Crear tabla projects con todas las columnas necesarias incluyendo soporte para PostGIS y configuracion de indices compuestos para optimizar queries + +# Sin tipo +[FE-008] Mejorar componente +``` + +--- + +## TIPOS DE COMMITS + +| Tipo | Uso | Ejemplo | +|------|-----|---------| +| `feat` | Nueva funcionalidad | `[DB-042] feat: Agregar soporte PostGIS` | +| `fix` | Correccion de bug | `[BE-015] fix: Resolver error en constraint` | +| `refactor` | Refactorizacion sin cambio funcional | `[FE-008] refactor: Mejorar estructura componentes` | +| `docs` | Solo documentacion | `[DB-042] docs: Actualizar README con schema` | +| `test` | Agregar/modificar tests | `[BE-015] test: Agregar tests para ProjectService` | +| `chore` | Tareas de mantenimiento | `[DB-042] chore: Actualizar dependencias` | +| `style` | Formato/estilo (sin cambio logico) | `[FE-008] style: Aplicar prettier` | +| `perf` | Mejora de performance | `[DB-042] perf: Agregar indice compuesto` | +| `build` | Cambios en build/deps | `[BE-015] build: Actualizar TypeORM a v0.3` | +| `ci` | Cambios en CI/CD | `[INFRA-001] ci: Agregar workflow de tests` | + +--- + +## COMMITS ATOMICOS + +### Que es un Commit Atomico + +```yaml +atomico: + - Representa UN cambio logico completo + - Es funcional (build pasa) + - Es reversible individualmente + - No mezcla cambios no relacionados + +NO_atomico: + - Multiples cambios no relacionados + - Trabajo incompleto (excepto WIP explicito) + - Mezcla de fix y feat + - Cambios en multiples features +``` + +### Ejemplo de Atomicidad + +```bash +# CORRECTO - Commits atomicos separados +[DB-042] feat: Crear tabla projects +[DB-042] feat: Agregar indices a tabla projects +[DB-042] feat: Crear seeds para projects +[DB-042] docs: Actualizar inventario con tabla projects + +# INCORRECTO - Un commit masivo +[DB-042] feat: Crear tabla projects con indices, seeds y actualizacion de inventario +``` + +--- + +## FLUJO DE TRABAJO GIT + +### Antes de Empezar Tarea + +```bash +# 1. Asegurar rama actualizada +git fetch origin +git pull origin main + +# 2. Crear rama de trabajo (si aplica) +git checkout -b feature/{TAREA-ID}-descripcion-corta + +# 3. Verificar estado limpio +git status +``` + +### Durante la Tarea + +```bash +# 1. Hacer cambios +# ... editar archivos ... + +# 2. Verificar que build pasa +npm run build +npm run lint + +# 3. Agregar cambios +git add {archivos especificos} +# o para todos los cambios relacionados: +git add . + +# 4. Commit con mensaje descriptivo +git commit -m "[TAREA-ID] tipo: descripcion" + +# 5. Repetir para cada cambio logico +``` + +### Al Completar Tarea + +```bash +# 1. Verificar historial +git log --oneline -5 + +# 2. Push a remoto +git push origin {rama} + +# 3. Crear PR si aplica +gh pr create --title "[TAREA-ID] Descripcion" --body "..." +``` + +--- + +## CHECKLIST PRE-COMMIT + +```yaml +ANTES_de_cada_commit: + - [ ] Build pasa sin errores + - [ ] Lint pasa sin errores criticos + - [ ] Tests pasan (si existen) + - [ ] Cambios son logicamente completos + - [ ] No hay archivos no deseados (node_modules, .env, etc.) + - [ ] Mensaje sigue formato correcto + +VERIFICAR: + git status # Ver archivos modificados + git diff # Ver cambios en detalle + git diff --cached # Ver cambios staged +``` + +--- + +## ERRORES COMUNES + +| Error | Consecuencia | Solucion | +|-------|--------------|----------| +| No commitear frecuentemente | Perdida de trabajo | Commit cada 30-45 min | +| Commits masivos | Dificil revertir | Commits atomicos | +| Mensajes vagos | Historial incomprensible | Seguir formato | +| Commit con build roto | Bloquea CI/CD | Verificar antes de commit | +| Olvidar ID de tarea | Perdida de trazabilidad | Siempre incluir [TAREA-ID] | +| Commitear secretos | Brecha de seguridad | Verificar .gitignore | + +--- + +## ARCHIVOS A IGNORAR (.gitignore) + +```yaml +SIEMPRE_ignorar: + - node_modules/ + - .env + - .env.* + - dist/ + - build/ + - coverage/ + - *.log + - .DS_Store + - *.tmp + - *.cache + +NUNCA_commitear: + - Credenciales + - API keys + - Passwords + - Certificados privados + - Archivos de configuracion local +``` + +--- + +## RAMAS (BRANCHING) + +### Convencion de Nombres + +```yaml +ramas: + feature: feature/{TAREA-ID}-descripcion-corta + bugfix: bugfix/{TAREA-ID}-descripcion-corta + hotfix: hotfix/{TAREA-ID}-descripcion-corta + release: release/v{X.Y.Z} + +ejemplos: + - feature/DB-042-crear-tabla-projects + - bugfix/BE-015-fix-validacion + - hotfix/SEC-001-fix-xss + - release/v2.1.0 +``` + +### Flujo de Ramas + +``` +main (produccion) + │ + ├─── develop (desarrollo) + │ │ + │ ├─── feature/DB-042-* + │ │ └── merge a develop + │ │ + │ ├─── feature/BE-015-* + │ │ └── merge a develop + │ │ + │ └── release/v2.1.0 + │ └── merge a main + tag + │ + └─── hotfix/SEC-001-* + └── merge a main + develop +``` + +--- + +## REVERTIR CAMBIOS + +### Revertir Ultimo Commit (no pusheado) + +```bash +# Mantener cambios en working directory +git reset --soft HEAD~1 + +# Descartar cambios completamente +git reset --hard HEAD~1 +``` + +### Revertir Commit ya Pusheado + +```bash +# Crear commit de reversion (seguro) +git revert {commit-hash} +git push +``` + +### Deshacer Cambios en Archivo + +```bash +# Descartar cambios no staged +git checkout -- {archivo} + +# Descartar cambios staged +git reset HEAD {archivo} +git checkout -- {archivo} +``` + +--- + +## SITUACIONES ESPECIALES + +### Work in Progress (WIP) + +```bash +# Cuando necesitas commitear trabajo incompleto +git commit -m "[TAREA-ID] WIP: descripcion de estado actual" + +# Luego, completar y hacer commit final +# (opcional: squash commits WIP antes de PR) +``` + +### Antes de Lanzar Subagente + +```bash +# SIEMPRE commitear antes de delegar +git add . +git commit -m "[TAREA-ID] chore: Estado antes de delegacion a {SubAgente}" +``` + +### Despues de Validar Subagente + +```bash +# Commitear resultado de subagente +git add . +git commit -m "[TAREA-ID-SUB-XXX] tipo: Resultado de {SubAgente}" +``` + +--- + +## VALIDACION DE COMMITS + +### Verificar Historial + +```bash +# Ver ultimos commits +git log --oneline -10 + +# Ver commits de tarea especifica +git log --oneline --grep="DB-042" + +# Ver cambios de un commit +git show {commit-hash} +``` + +### Verificar Formato de Mensaje + +```yaml +formato_valido: + - Tiene [TAREA-ID] al inicio + - Tiene tipo valido (feat, fix, etc.) + - Descripcion concisa (<72 caracteres primera linea) + - No tiene errores de ortografia graves + +verificar_manualmente: + git log --oneline -1 + # Debe mostrar: {hash} [TAREA-ID] tipo: descripcion +``` + +--- + +## REFERENCIAS + +- **Principio de Validacion:** @PRINCIPIOS/PRINCIPIO-VALIDACION-OBLIGATORIA.md +- **Documentar:** @SIMCO/SIMCO-DOCUMENTAR.md +- **Crear:** @SIMCO/SIMCO-CREAR.md + +--- + +**Version:** 1.0.0 | **Sistema:** SIMCO | **Mantenido por:** Tech Lead diff --git a/orchestration/directivas/simco/SIMCO-TAREA.md b/orchestration/_archive/directivas/simco/SIMCO-TAREA.md similarity index 100% rename from orchestration/directivas/simco/SIMCO-TAREA.md rename to orchestration/_archive/directivas/simco/SIMCO-TAREA.md diff --git a/orchestration/directivas/simco/SIMCO-VALIDAR.md b/orchestration/_archive/directivas/simco/SIMCO-VALIDAR.md similarity index 100% rename from orchestration/directivas/simco/SIMCO-VALIDAR.md rename to orchestration/_archive/directivas/simco/SIMCO-VALIDAR.md diff --git a/orchestration/directivas/triggers/TRIGGER-ANALISIS-DEPENDENCIAS.md b/orchestration/_archive/directivas/triggers/TRIGGER-ANALISIS-DEPENDENCIAS.md similarity index 100% rename from orchestration/directivas/triggers/TRIGGER-ANALISIS-DEPENDENCIAS.md rename to orchestration/_archive/directivas/triggers/TRIGGER-ANALISIS-DEPENDENCIAS.md diff --git a/orchestration/directivas/triggers/TRIGGER-ANTI-DUPLICACION.md b/orchestration/_archive/directivas/triggers/TRIGGER-ANTI-DUPLICACION.md similarity index 100% rename from orchestration/directivas/triggers/TRIGGER-ANTI-DUPLICACION.md rename to orchestration/_archive/directivas/triggers/TRIGGER-ANTI-DUPLICACION.md diff --git a/orchestration/directivas/triggers/TRIGGER-CIERRE-TAREA-OBLIGATORIO.md b/orchestration/_archive/directivas/triggers/TRIGGER-CIERRE-TAREA-OBLIGATORIO.md similarity index 100% rename from orchestration/directivas/triggers/TRIGGER-CIERRE-TAREA-OBLIGATORIO.md rename to orchestration/_archive/directivas/triggers/TRIGGER-CIERRE-TAREA-OBLIGATORIO.md diff --git a/orchestration/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md b/orchestration/_archive/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md similarity index 100% rename from orchestration/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md rename to orchestration/_archive/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md diff --git a/orchestration/directivas/triggers/TRIGGER-COMMIT-PUSH-OBLIGATORIO.md b/orchestration/_archive/directivas/triggers/TRIGGER-COMMIT-PUSH-OBLIGATORIO.md similarity index 100% rename from orchestration/directivas/triggers/TRIGGER-COMMIT-PUSH-OBLIGATORIO.md rename to orchestration/_archive/directivas/triggers/TRIGGER-COMMIT-PUSH-OBLIGATORIO.md diff --git a/orchestration/directivas/triggers/TRIGGER-FETCH-OBLIGATORIO.md b/orchestration/_archive/directivas/triggers/TRIGGER-FETCH-OBLIGATORIO.md similarity index 100% rename from orchestration/directivas/triggers/TRIGGER-FETCH-OBLIGATORIO.md rename to orchestration/_archive/directivas/triggers/TRIGGER-FETCH-OBLIGATORIO.md diff --git a/orchestration/directivas/triggers/TRIGGER-INICIO-TAREA.md b/orchestration/_archive/directivas/triggers/TRIGGER-INICIO-TAREA.md similarity index 100% rename from orchestration/directivas/triggers/TRIGGER-INICIO-TAREA.md rename to orchestration/_archive/directivas/triggers/TRIGGER-INICIO-TAREA.md diff --git a/orchestration/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md b/orchestration/_archive/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md similarity index 100% rename from orchestration/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md rename to orchestration/_archive/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md diff --git a/orchestration/environment/ENVIRONMENT-INVENTORY.yml b/orchestration/_archive/environment/ENVIRONMENT-INVENTORY.yml similarity index 100% rename from orchestration/environment/ENVIRONMENT-INVENTORY.yml rename to orchestration/_archive/environment/ENVIRONMENT-INVENTORY.yml diff --git a/orchestration/referencias/DEPENDENCIAS-ERP-CORE.yml b/orchestration/_archive/referencias/DEPENDENCIAS-ERP-CORE.yml similarity index 100% rename from orchestration/referencias/DEPENDENCIAS-ERP-CORE.yml rename to orchestration/_archive/referencias/DEPENDENCIAS-ERP-CORE.yml