USER_MANUAL.es.md

Evolith Tracker: Manual de Uso

El modelo operativo de la plataforma: qué gobierna, cómo funciona el embudo SDLC, cómo se configuran los gates y los criterios de control, y exactamente cuándo entran en juego un repositorio gobernado y su evolith.yaml.

¿Recién llegas? Empieza por el Inicio Rápido.

1. Alcance

Evolith Tracker es un plano de control de gobernanza SDLC con apoyo advisory de arquitectura técnica. Su unidad de gobernanza es la Iniciativa; no gestiona detalle de implementación (tareas, backlogs, user stories, épicas). Productos, tenants e iniciativas son contexto de gobernanza, nunca entidades dentro del Core — el Core es un motor de evaluación stateless que recibe un contexto de evaluación y devuelve un resultado.

2. Los dos planos de gobernanza

Esta es la idea más importante de la plataforma. La gobernanza se entrega en dos planos independientes.

Plano 1 — Gobernanza SDLC / proceso (siempre activo)

Fases, gates, criterios de control, evidencia, aprobaciones multi-PO y auditoría. Es la máquina de estados del propio Tracker y aplica a todos los tenants e iniciativas. No requiere repositorio de código ni evolith.yaml. La mayor parte del valor de gobernanza vive aquí.

Plano 2 — Conformidad técnica de arquitectura (opt-in)

El Evolith Core evalúa un repositorio gobernado (un "satélite") contra los rulesets, leyendo el evolith.yaml del repositorio para saber qué está evaluando. Este plano solo se activa cuando hay un satélite que evaluar.

El interruptor

Cada política de gate lleva un flag requiresCoreVerdict:

• requiresCoreVerdict: false (el default) — el gate se resuelve con evidencia más aprobaciones. Nunca se llama al Core; no se necesita ningún evolith.yaml.
• requiresCoreVerdict: true — el gate además exige un veredicto del Core con resultado PASS. Solo tiene sentido para una iniciativa cuyo producto apunta a un repositorio satélite.

Un tenant que corre solo iniciativas de negocio, sin repositorios gobernados, opera por completo en el Plano 1 y nunca ve un evolith.yaml. Encender el Plano 2 es una decisión por gate, tomada donde la conformidad técnica de arquitectura realmente importa (típicamente los gates de Design y Construction de iniciativas de software).

3. Multi-tenancy

Esto es un SaaS multi-tenant: un tenant ve solo su propia información. Toda superficie operativa está scoped al tenant autenticado; el nombre del tenant se muestra en solo lectura en el chrome superior, nunca un identificador interno.

La única excepción es un platform operator (por ejemplo Evolith Platform - root), que tiene una capacidad cross-tenant y puede cambiar el tenant sobre el que opera vía el selector de la barra superior. El backend lo impone: un override a otro tenant se acepta solo para un principal con la capacidad de plataforma; cualquier otro intento cross-tenant se rechaza. Bajo el proveedor local dev-bypass toda sesión es un platform operator, por eso el selector aparece en local.

4. El embudo SDLC y las tres vías de entrada

Una iniciativa fluye por: Intake -> Discovery -> Design -> Construction -> QA -> Release -> Done. Los nombres de fase son minúsculas en la API (discovery, design, construction, qa, release, done). El orden de fases se impone — un gate posterior queda not-ready hasta que los gates previos estén aprobados.

Las iniciativas entran por una de tres vías, y las tres convergen en la misma iniciativa rica de Discovery:

1. Strategic intake — la iniciativa llega de un PPM, ya financiada y priorizada, con su business case afirmado. Corre el filtro advisory de factibilidad y luego promueve a Discovery. (El Tracker es un receptor aquí; nunca recalcula el business case.)
2. Opportunity — un candidato pre-Discovery capturado con contexto útil (problema, valor esperado, tamaño estimado, sponsor, producto objetivo, tema estratégico). Trialo y luego promueve los más fuertes a iniciativa, de modo que la iniciativa promovida quede sembrada en lugar de vacía.
3. Manual — crea la iniciativa directamente con su detalle completo de Discovery.

El tipo de iniciativa se deriva del alcance de productos: cero productos -> tenant-wide; uno -> single-product; dos o más -> cross-product. El tipo determina qué criterios de gate y facetas por producto aplican.

5. Gates y criterios de control

Gate governance es un motor configurable con tres partes:

• Política de gate (configuración, por tenant y fase) — los criterios de control: modo del gate, evidencia requerida, cadena de aprobadores, y si un veredicto del Core es obligatorio (requiresCoreVerdict). Se configuran en la pantalla Gate governance.
• Gate submission (proceso, por iniciativa y fase) — una solicitud de pasar un gate, portando evidencia y moviéndose por decisiones. RETURNED es no terminal y reworkeable; solo APPROVED y REJECTED son terminales.
• Evidencia y aprobaciones — los registros de evidencia se adjuntan y verifican; la cadena de aprobadores se deriva del tipo de iniciativa y la propiedad del producto, y cada aprobador requerido decide.

Para los gates de discovery y design la submission se crea directamente; para construction, QA y release se completan los artefactos de fase y el gate adjunta automáticamente los ítems de artefacto completos como evidencia. Aprobar un gate avanza la progresión de fase.

6. evolith.yaml y satélites

Qué es

evolith.yaml es el manifiesto de un repositorio gobernado (un satélite), que vive en la raíz del repositorio. Declara qué es el repositorio y cómo se gobierna:

{
  "coreRef":    { "version": "1.0.0", "path": "../evolith" }, // qué Core lo gobierna
  "governance": { "version": "1.0.0" },
  "product":    { "name": "checkout", "type": "enterprise-application", "phase": "phase-0" },
  "tools":      { "runtime": "nodejs", "architecture": "clean", "database": "postgresql", "api": "rest", "ci": "github" }
}

El Core lo lee para saber qué está evaluando. Su ruleset validator exige el manifiesto en la raíz del satélite (regla GOV-000; el contrato OPA SVC-01); sin él, el Core reporta una violación bloqueante "Missing evolith.yaml".

¿Cada producto necesita uno?

evolith.yaml es por repositorio gobernado, no por producto en abstracto. Un producto necesita un manifiesto por cada repositorio gobernado que posea — normalmente un producto mapea a un repositorio y un manifiesto, pero un producto puede abarcar varios repositorios (cada uno su propio satélite) o usar un monorepo (un solo manifiesto en la raíz). Un producto sin repositorio todavía — una idea en Discovery, o una iniciativa no-software — no tiene ninguno y no necesita ninguno, porque no hay código para que el Core evalúe.

El agregado Product ya modela RepositoryUrl (y Topology): esa URL de repositorio es el puntero al satélite.

¿Y los productos y tenants sin satélites?

Conservan gobernanza completa — el Plano 1 los cubre por entero. Sus gates simplemente corren con requiresCoreVerdict: false y nunca llaman al Core, así que nunca interviene un evolith.yaml. Nada falta y nada se rompe: la conformidad de arquitectura es una capa advisory que se enchufa solo donde existe código gobernado.

7. La evaluación advisory del Core

Más allá de la conformidad de gate, el Core provee apoyo advisory que el Tracker expone:

• Recomendación de topología y madurez del design blueprint — calculadas desde los datos propios de la iniciativa en el Tracker (facetas del blueprint). Estas no requieren un satélite.
• Conformidad del repositorio — el chequeo más profundo que evalúa el evolith.yaml de un satélite más sus fuentes contra los rulesets. Esta es la única capa que requiere un satélite.

El Tracker arma el contexto; el Core evalúa lo que recibe. El Tracker se conecta al repositorio satélite de un producto usando el acceso por-producto (URL + credenciales cifradas), lee el manifiesto y un conjunto curado de fuentes y docs, lo ensambla en un contexto de evaluación inline y lo envía al Core. El Core recibe identificadores opacos de tenant/product/initiative más el contenido ensamblado, y evalúa el contenido recibido — no clona, no lee filesystem, no resuelve un workspaceRef a una ruta ni toca red. Sigue stateless.

En concreto: configura el acceso al repositorio de un producto (Products → un producto → Repository access) y luego POST /api/products/{id}/evaluate-architecture. El Tracker trae el repo vía la API del proveedor (GitHub primero), arma evaluationInput.files (incluyendo evolith.yaml) y lo envía al Core, que monta esos archivos como el satélite en memoria y corre los mismos rulesets. Si el repo no tiene evolith.yaml, el Core devuelve un resultado advisory genuino que reporta el manifiesto ausente (GOV-000). Cada corrida queda registrada como una core evaluation transaction. (Los inputs legacy workspaceRef/satellitePath siguen soportados por retro-compatibilidad, pero el contenido inline es el camino canónico.)

8. Productos, oportunidades y configuración de tenant

• Productos — el catálogo; cada producto lleva una topología, una URL de repositorio (su puntero al satélite) y un dueño. Un código de producto es único dentro de un tenant.
• Oportunidades — el registro de candidatos pre-Discovery, capturando contexto liviano pero útil de modo que una oportunidad promovida siembre una iniciativa rica. Un código de oportunidad es único dentro de un tenant.
• Tenant intelligence — la configuración de gobernanza propia de cada tenant: model routing, referencias de corpus, registros de agentes y settings. Es una superficie de configuración, mantenida separada de las superficies de datos y proceso.
• Conectores (PPM intake) — registrados por tenant, en los parámetros propios del tenant, alimentando el Strategic intake.
• Regionalización y localización — el país, locale, moneda y zona horaria del tenant gobiernan el formato de dinero y fechas. Estos pasan de campos de texto libre a catálogos maestros validados (países, jerarquías territoriales con códigos oficiales/ubigeo, monedas ISO 4217, zonas horarias IANA), de modo que el usuario selecciona valores válidos en lugar de escribirlos. Vive en el contexto acotado Geo / datos maestros (esquema geo), accedido solo por el puerto IMasterDataDirectory y diseñado para extraerse luego como servicio compartido evolith_mms. Ver T-032 y el diagrama Geo.

9. Sembrar datos de demostración

node src/apps/tracker-api/seed/seed-e2e.mjs

Puebla tres tenants coherentes por todo el embudo (ver el Inicio Rápido para detalles). Úsalo para explorar flujos completos — fases, artefactos, criterios de control, submissions de gate, evidencia y configuraciones — y, para un platform operator, para comparar tenants lado a lado mediante el selector de la barra superior.

10. Ejecución local

Ver el Inicio Rápido, sección 3, y el bloque "Local development commands" en el README del repositorio.