From d18ee247aa106e017f5c770498906ef820fb6bd1 Mon Sep 17 00:00:00 2001 From: aarroyo Date: Mon, 13 Jul 2026 11:08:06 -0500 Subject: [PATCH 1/3] =?UTF-8?q?docs(governance):=20ADR-0111=20Quality=20Si?= =?UTF-8?q?gnal=20Provider=20port=20+=20register=20evidence-adapter=20wave?= =?UTF-8?q?=20GT-533=E2=80=A6537?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-0111 fixes the seam through which external quality/evidence tools (Lighthouse, TestSprite, Claude SEO, thermo-nuclear) enrich Evolith Core via adapters and a canonical Evidence model — per-tenant selectable, provenance + determinism mandatory, never a Core dependency. Generalizes the GT-530 ObservabilityEvidence adapter into one uniform seam. Registers the wave on the gap board (EN/ES tracking + catalog): - GT-533 Quality Signal Provider port + Evidence model + per-tenant registry (P1) - GT-534 Lighthouse reference adapter, prototype-first (P1) - GT-535 thermo-nuclear structural-review rubric → code-quality agent + gate (P1) - GT-536 TestSprite test-evidence adapter, opt-in default-off (P2, deferred) - GT-537 GEO/AI-discoverability Scorecards pack, Claude SEO pattern (P3, deferred) Co-Authored-By: Claude Opus 4.8 --- .../core/architecture/adrs/adr-matrix.es.md | 1 + .../core/architecture/adrs/adr-matrix.md | 1 + .../0111-quality-signal-provider-port.es.md | 230 ++++++++++++++++++ .../core/0111-quality-signal-provider-port.md | 224 +++++++++++++++++ .../core/architecture/adrs/core/README.es.md | 1 + .../core/architecture/adrs/core/README.md | 1 + .../gaps/gap-reference-catalog.es.md | 91 +++++++ .../gaps/gap-reference-catalog.md | 91 +++++++ .../control-center/gaps/gap-tracking.es.md | 7 +- .../core/control-center/gaps/gap-tracking.md | 7 +- 10 files changed, 652 insertions(+), 2 deletions(-) create mode 100644 reference/core/architecture/adrs/core/0111-quality-signal-provider-port.es.md create mode 100644 reference/core/architecture/adrs/core/0111-quality-signal-provider-port.md diff --git a/reference/core/architecture/adrs/adr-matrix.es.md b/reference/core/architecture/adrs/adr-matrix.es.md index 61606d1cb..b231721dc 100644 --- a/reference/core/architecture/adrs/adr-matrix.es.md +++ b/reference/core/architecture/adrs/adr-matrix.es.md @@ -16,6 +16,7 @@ Usa esta matriz cuando necesites encontrar decisiones por preocupación y no por | Observabilidad y operaciones | [nodejs/ADR-0007](./nodejs/0007-observability-telemetry-loki-opentelemetry.es.md), [core/ADR-0046](./core/0046-unified-observability-tracecontext.es.md), [core/ADR-0013](./core/0013-cloud-infrastructure-topology-dr.es.md), [dotnet/ADR-0064](./dotnet/0064-dotnet-request-scope-observability-context.es.md), [dotnet/ADR-0065](./dotnet/0065-dotnet-pii-safe-serilog-pipeline.es.md) | SRE, DevOps, Backend | Universal más específico por runtime | | Confiabilidad API e idempotencia | [dotnet/ADR-0063](./dotnet/0063-dotnet-b2b-idempotency-middleware.es.md), [dotnet/ADR-0066](./dotnet/0066-dotnet-lightweight-http-idempotency.es.md) | Backend, SRE | .NET | | Testing y calidad | [core/ADR-0018](./core/0018-testing-pyramid-quality-gates.es.md), [core/ADR-0052](./core/0052-unit-testing-isolation-strategy.es.md), [core/ADR-0053](./core/0053-integration-e2e-testing-strategy.es.md) | QA, Desarrolladores | Universal | +| Señales de calidad y evidencia externa | [core/ADR-0111](./core/0111-quality-signal-provider-port.es.md), [core/ADR-0005](./core/0005-automated-sast-quality-gates.es.md), [core/ADR-0104](./core/0104-topology-driven-advisory-design-governance.es.md) | Arquitectos, QA, Plataforma, agentes IA | Universal | | Frontend y modularidad UI | [nodejs/ADR-0004](./nodejs/0004-frontend-offline-resilience.es.md), [core/ADR-0055](./core/0055-microfrontends-architecture-strategy.es.md), [nodejs/ADR-0044](./nodejs/0044-frontend-clean-architecture-layer-boundaries.es.md), [nodejs/ADR-0045](./nodejs/0045-zustand-tanstack-query-state-management.es.md) | Frontend, Arquitectos | Universal más implementación frontend | | Estándares UX Frontend | [nodejs/ADR-0046](./nodejs/0046-no-raw-identifiers-in-ui.es.md), [nodejs/ADR-0047](./nodejs/0047-actionable-user-error-contract.es.md), [core/ADR-0072](./core/0072-utc-dates-timezone-language-resolution.es.md) | Frontend, UX, Backend | Universal | | Feature flags internos | [core/ADR-0017](./core/0017-feature-flagging-strategy.es.md), [core/ADR-0025](./core/0025-feature-flag-provider-abstraction.es.md), [nodejs/ADR-0048](./nodejs/0048-feature-flag-system-scope-criteria-model.es.md) | Backend, Arquitectos | Universal | diff --git a/reference/core/architecture/adrs/adr-matrix.md b/reference/core/architecture/adrs/adr-matrix.md index 4b1874763..0f06c673d 100644 --- a/reference/core/architecture/adrs/adr-matrix.md +++ b/reference/core/architecture/adrs/adr-matrix.md @@ -16,6 +16,7 @@ Use this matrix when you need to find decisions by concern instead of by numeric | Observability and operations | [nodejs/ADR-0007](./nodejs/0007-observability-telemetry-loki-opentelemetry.md), [core/ADR-0046](./core/0046-unified-observability-tracecontext.md), [core/ADR-0013](./core/0013-cloud-infrastructure-topology-dr.md), [dotnet/ADR-0064](./dotnet/0064-dotnet-request-scope-observability-context.md), [dotnet/ADR-0065](./dotnet/0065-dotnet-pii-safe-serilog-pipeline.md) | SRE, DevOps, Backend | Universal plus runtime-specific | | API reliability and idempotency | [dotnet/ADR-0063](./dotnet/0063-dotnet-b2b-idempotency-middleware.md), [dotnet/ADR-0066](./dotnet/0066-dotnet-lightweight-http-idempotency.md) | Backend, SRE | .NET | | Testing and quality | [core/ADR-0018](./core/0018-testing-pyramid-quality-gates.md), [core/ADR-0052](./core/0052-unit-testing-isolation-strategy.md), [core/ADR-0053](./core/0053-integration-e2e-testing-strategy.md) | QA, Developers | Universal | +| Quality signals & external evidence | [core/ADR-0111](./core/0111-quality-signal-provider-port.md), [core/ADR-0005](./core/0005-automated-sast-quality-gates.md), [core/ADR-0104](./core/0104-topology-driven-advisory-design-governance.md) | Architects, QA, Platform, AI agents | Universal | | Frontend and UI modularity | [nodejs/ADR-0004](./nodejs/0004-frontend-offline-resilience.md), [core/ADR-0055](./core/0055-microfrontends-architecture-strategy.md), [nodejs/ADR-0044](./nodejs/0044-frontend-clean-architecture-layer-boundaries.md), [nodejs/ADR-0045](./nodejs/0045-zustand-tanstack-query-state-management.md) | Frontend, Architects | Universal plus frontend implementation | | Frontend UX standards | [nodejs/ADR-0046](./nodejs/0046-no-raw-identifiers-in-ui.md), [nodejs/ADR-0047](./nodejs/0047-actionable-user-error-contract.md), [core/ADR-0072](./core/0072-utc-dates-timezone-language-resolution.md) | Frontend, UX, Backend | Universal | | Feature flag internals | [core/ADR-0017](./core/0017-feature-flagging-strategy.md), [core/ADR-0025](./core/0025-feature-flag-provider-abstraction.md), [nodejs/ADR-0048](./nodejs/0048-feature-flag-system-scope-criteria-model.md) | Backend, Architects | Universal | diff --git a/reference/core/architecture/adrs/core/0111-quality-signal-provider-port.es.md b/reference/core/architecture/adrs/core/0111-quality-signal-provider-port.es.md new file mode 100644 index 000000000..09f5ac3e5 --- /dev/null +++ b/reference/core/architecture/adrs/core/0111-quality-signal-provider-port.es.md @@ -0,0 +1,230 @@ +> **Navegación bilingüe:** [View English version](./0111-quality-signal-provider-port.md) + +# ADR-0111: Puerto de Proveedores de Señales de Calidad — Evidencia Externa vía Adaptadores + +> **Firma del agente:** Agente Arquitecto (Winston) + +## Estado +Propuesto (2026-07-13 — Consejo de Arquitectura) + +## Fecha +2026-07-13 + +## Contexto y Problema + +Evolith Core es un Motor de Evaluación stateless y determinista: recibe un +`EvaluationContext` y devuelve un `EvaluationResult`, gobernado por contratos, +rulesets y OPA ([ADR-0101](./0101-core-stateless-evaluation-engine.md)). La suite +se posiciona como una capa de *gobernanza de arquitectura para la era de la IA* +que conecta las decisiones arquitectónicas con la calidad técnica, el testing, el +performance, la documentación y la ejecución a lo largo del SDLC. + +Cumplir ese posicionamiento exige **evidencia**: los criterios que el Core deriva +de un diseño/blueprint ([ADR-0104](./0104-topology-driven-advisory-design-governance.md)) +valen lo que valgan las señales que confirman o refutan la conformidad en build y +runtime. Ya existe un ecosistema rico de herramientas externas que producen esas +señales — auditores de runtime (p. ej. Lighthouse), plataformas de testing +autónomo (p. ej. TestSprite), auditores de contenido/discoverability +multi-agente (p. ej. Claude SEO) y metodologías de revisión estructural de código +(p. ej. la rúbrica de revisión "thermo-nuclear"). + +El riesgo es obvio y recurrente: si el Core — o cada superficie (CLI, Portal, +agent-runtime) — integra estas herramientas directamente, acoplamos un motor +determinista a tecnología volátil de terceros, metemos red/side-effects en un +evaluador stateless, filtramos código a nubes externas y hacemos crecer N×M +integraciones a medida sin normalización, sin provenance y sin política uniforme. + +El problema: **¿cómo enriquecen las herramientas externas de calidad/evidencia la +evaluación del Evolith Core sin convertirse jamás en dependencia del Core, y +dejando que cada tenant elija cuáles están activas?** + +## Objetivo y Alcance + +Definir la costura por la que cualquier productor externo de calidad/evidencia +alimenta al Core. En alcance: (1) un único puerto de salida +`IQualitySignalProvider`, (2) un modelo canónico `Evidence` con provenance +obligatoria, (3) la regla de que el Core consume `Evidence` **inline en su +contexto** y nunca ejecuta proveedores, y (4) un **registro** de proveedores +declarativo y por tenant que selecciona qué adaptadores están activos. + +Fuera de alcance: las implementaciones concretas de los adaptadores y sus +elecciones específicas de proveedor (cada una se delega a un ADR de Plataforma +acompañante, p. ej. un ADR Node.js para el adaptador Lighthouse), y los productos +de scorecard/gate que consumen la evidencia resultante (se registran aparte). + +## Opciones Consideradas + +### Opción A: El Core llama a las herramientas directamente + +Que `core-domain` invoque Lighthouse/TestSprite/etc. durante la evaluación. +Rechazada: rompe la statelessness ([ADR-0101](./0101-core-stateless-evaluation-engine.md)), +mete I/O de red y side-effects no deterministas dentro del motor determinista, y +acopla el Core a herramientas concretas. + +### Opción B: Una integración a medida por herramienta en cada superficie + +Cada superficie (CLI, Portal, agent-runtime) cablea cada herramienta ad hoc. +Rechazada: drift N×M, sin normalización compartida, provenance inconsistente (o +ausente), y sin forma de evaluar las señales uniformemente contra política. +Además reimplementa el trabajo de adaptador/normalización ya establecido para los +connectors Port/Cortex y Jira. + +### Opción C: Puerto único de proveedor + ACL canónica de Evidence + registro por tenant (elegida) + +Los productores externos implementan un puerto de salida y emiten un objeto +`Evidence` normalizado (una capa anticorrupción). La capa de orquestación ejecuta +los proveedores *activos*, recolecta `Evidence[]` y la pasa inline al Core. Un +registro por tenant declara qué proveedores están activos. Elegida: mantiene el +Core puro, hace cada proveedor enchufable, elegible por tenant y desechable, y +reutiliza el patrón connector-adaptador que la suite ya practica. + +## Decisión y Fundamentos + +### 1. Un puerto de salida, propiedad de la orquestación — no del Core + +`IQualitySignalProvider` vive en la capa de orquestación/aplicación +(agent-runtime y las superficies del SDLC), **no** en `core-domain`. Todo el I/O +del proveedor — Chrome headless, llamadas a la nube, auditorías LLM — ocurre +detrás de este puerto. + +```ts +// capa de orquestación (NO core-domain) +interface IQualitySignalProvider { + readonly id: string; // "lighthouse" | "testsprite" | ... + supports(ctx: CollectionContext): boolean; + collect(target: CollectionTarget): Promise; +} +``` + +### 2. El Core solo conoce el modelo canónico `Evidence` + +`Evidence` es la única superficie que ve el Core. Entra en el `EvaluationContext` +**inline**, exactamente como hoy entran los archivos fuente vía el precedente de +repository-access / `OverlayFileSystem` ([ADR-0080](./0080-remote-repository-reference-contract.md), +[ADR-0101](./0101-core-stateless-evaluation-engine.md)). El Core es indiferente a +qué herramienta produjo una señal. + +```ts +// core-domain — lo ÚNICO que el Core importa +interface Evidence { + source: string; // opaco para el Core + dimension: string; // "performance" | "a11y" | "code-quality" | "testing" | ... + metrics: Record; + findings: Finding[]; + determinism: 'deterministic' | 'probabilistic'; // Lighthouse vs basado en LLM + provenance: Provenance; // collectedBy, adapterVersion, artifactHash, timestamp +} +``` + +### 3. El Core nunca ejecuta proveedores + +La recolección es un asunto de orquestación con side-effects. El Core recibe +`Evidence[]` ya recolectada y la evalúa contra criterios derivados y política. +Esto preserva el determinismo y mantiene al evaluador libre de red y de +acoplamiento a proveedores. Si una dimensión no tiene evidencia, el Core la +reporta como `no-evidence`, nunca como un fallo que él causó. + +### 4. Los proveedores se seleccionan por tenant, de forma declarativa + +Un registro por tenant (mismo espíritu que el SSOT del registro de skills y el +manifest de `.harness`, respetando el aislamiento multi-tenant — +[ADR-0010](./0010-multi-tenancy-architecture-strategy.md), +[ADR-0106](./0106-master-tenant-context-projections.md)) declara qué proveedores +están activos y su configuración. La selección es opt-in y vive en configuración, +no en el Core. + +```yaml +qualitySignals: + providers: + - { id: lighthouse, enabled: true, config: { categories: [performance, a11y, seo] } } + - { id: thermo-nuclear, enabled: true } + - { id: testsprite, enabled: false } # nube/propietario → opt-in, off por defecto +``` + +### 5. Los adaptadores viven en el borde, con frontera vigilada + +Los adaptadores concretos viven en `@evolith/infra-providers` (junto a los +connectors Port/Cortex y Jira), importados de forma lazy para que el paquete +compile con ninguno instalado. `lint:boundaries` prohíbe que cualquier import de +tercero o de adaptador llegue a `core-domain`. Los proveedores de nube/propietarios +(p. ej. TestSprite) aíslan su egress de código en la frontera del adaptador y por +defecto quedan deshabilitados. + +### 6. La provenance es obligatoria y gobierna + +Toda `Evidence` lleva provenance (`collectedBy` / `adapterVersion` / +`artifactHash` / `timestamp`) y un flag `determinism`, de modo que las señales son +auditables ([ADR-0016](./0016-immutable-business-audit-trail.md)) y la política +puede ponderarlas o hacer gate sobre ellas (p. ej. tratar la evidencia +probabilística como advisory y exigir evidencia determinista para un gate duro). + +## Evidencia y Criterios de Evaluación + +- **Statelessness preservada**: el Core importa solo `Evidence`; un grep debe + mostrar cero imports de proveedor/adaptador en `core-domain`. Mismo criterio + aplicado a Hermes en [ADR-0102](./0102-evolith-agent-runtime.md). +- **Precedente**: la ingesta de contexto inline ya funciona para archivos fuente + vía el modelo repository-access ([ADR-0080](./0080-remote-repository-reference-contract.md)); + `Evidence` sigue la forma idéntica. +- **Reutilización**: el patrón de adaptador de salida está probado por los + connectors Port/Cortex (GT-527) y Jira (GT-529); este ADR lo generaliza a los + productores de evidencia. +- **Exigibilidad**: la frontera del dominio es verificable por máquina vía + `lint:boundaries`. +- **Prueba de fuego (ADR de Core)**: si Lighthouse, TestSprite, Claude SEO y la + rúbrica thermo-nuclear desaparecieran mañana, la decisión (puerto + Evidence + canónica + registro) se mantiene — son adaptadores ilustrativos, no el sujeto + de la decisión. + +## Consecuencias, Riesgos y Trade-offs + +Positivo: el Core se mantiene puro y determinista; cualquier productor de +evidencia se vuelve enchufable, elegible por tenant y desechable; la provenance +hace cada señal auditable y evaluable por política; el lazo de conformidad +diseño/runtime ([ADR-0104](./0104-topology-driven-advisory-design-governance.md)) +se cierra con evidencia real. + +Negativo / trade-offs: una indirección extra (recolección → normalización → +evaluación); los proveedores difieren en determinismo, así que los consumidores +deben respetar el flag `determinism` en vez de tratar toda la evidencia por igual; +los proveedores probabilísticos (basados en LLM) requieren disciplina de +confianza/normalización. Riesgos: drift de adaptador o de registro (mitigado con +adaptadores versionados y un registro explícito) y egress de código para +proveedores de nube (mitigado con aislamiento en la frontera del adaptador y +opt-in off por defecto). Ningún proveedor puede jamás ser dependencia dura de la +suite. + +## Referencias + +- Lighthouse — motor de auditoría de runtime (Apache-2.0), API programática Node + con salida JSON: *(adaptador ilustrativo)* +- TestSprite — testing autónomo con IA; CLI/MCP OSS sobre nube propietaria (por + créditos): *(adaptador ilustrativo, opt-in)* +- Claude SEO — skill pack multi-agente MIT (patrón score + plan por severidad): + *(referencia de patrón)* +- Revisión de calidad thermo-nuclear — rúbrica de revisión estructural: + + *(referencia de metodología)* + +## Decisiones y Estándares Relacionados + +- [ADR-0101](./0101-core-stateless-evaluation-engine.md) — Core como Motor de + Evaluación stateless (el contrato que consume `Evidence`). +- [ADR-0102](./0102-evolith-agent-runtime.md) — capa agéntica de ports & adapters; + este ADR aplica el mismo principio a los productores de evidencia y reutiliza la + capa de orquestación que ejecuta los proveedores. +- [ADR-0104](./0104-topology-driven-advisory-design-governance.md) — deriva los + criterios que esta evidencia confirma o refuta (el lazo de conformidad). +- [ADR-0080](./0080-remote-repository-reference-contract.md) — precedente de + ingesta de contexto inline (`OverlayFileSystem`). +- [ADR-0010](./0010-multi-tenancy-architecture-strategy.md), + [ADR-0106](./0106-master-tenant-context-projections.md) — aislamiento de tenant + para el registro de proveedores por tenant. +- [ADR-0016](./0016-immutable-business-audit-trail.md) — garantías de + auditoría/provenance para la evidencia recolectada. +- [core/ADR-0005](./0005-automated-sast-quality-gates.md), + [core/ADR-0018](./0018-testing-pyramid-quality-gates.md) — consumidores de + quality-gate de la evidencia producida por este puerto. +- ADR de Plataforma acompañante (follow-on): adaptador Node.js para el proveedor + Lighthouse — registra la elección concreta de proveedor/runtime según el + estándar de autoría de ADRs. diff --git a/reference/core/architecture/adrs/core/0111-quality-signal-provider-port.md b/reference/core/architecture/adrs/core/0111-quality-signal-provider-port.md new file mode 100644 index 000000000..3d7b86e21 --- /dev/null +++ b/reference/core/architecture/adrs/core/0111-quality-signal-provider-port.md @@ -0,0 +1,224 @@ +> **Bilingual Navigation:** [Ver versión en Español](./0111-quality-signal-provider-port.es.md) + +# ADR-0111: Quality Signal Provider Port — External Evidence via Adapters + +> **Agent Signature:** Architect Agent (Winston) + +## Status +Proposed (2026-07-13 — Architecture Board) + +## Date +2026-07-13 + +## Context and Problem + +Evolith Core is a stateless, deterministic Evaluation Engine: it receives an +`EvaluationContext` and returns an `EvaluationResult`, governed by contracts, +rulesets and OPA ([ADR-0101](./0101-core-stateless-evaluation-engine.md)). The +suite positions itself as an *AI-era architecture governance* layer that +connects architectural decisions to technical quality, testing, performance, +documentation and execution across the SDLC. + +Delivering on that positioning requires **evidence**: the criteria that the Core +derives from a design/blueprint ([ADR-0104](./0104-topology-driven-advisory-design-governance.md)) +are only as strong as the signals that confirm or refute conformance at build +and runtime. A rich ecosystem of external tools already produces such signals — +runtime auditors (e.g. Lighthouse), autonomous test platforms (e.g. TestSprite), +multi-agent content/discoverability auditors (e.g. Claude SEO), and structural +code-review methodologies (e.g. the "thermo-nuclear" review rubric). + +The risk is obvious and recurrent: if the Core — or each surface (CLI, Portal, +agent-runtime) — integrates these tools directly, we couple a deterministic +engine to volatile third-party technology, introduce network/side-effects into a +stateless evaluator, leak code to external clouds, and grow N×M bespoke +integrations with no normalization, no provenance and no uniform policy. + +The problem: **how do external quality/evidence tools enrich Evolith Core's +evaluation without ever becoming a dependency of the Core, while letting each +tenant choose which of them are active?** + +## Objective and Scope + +Define the seam through which any external quality/evidence producer feeds the +Core. In scope: (1) a single driven port `IQualitySignalProvider`, (2) a +canonical `Evidence` model with mandatory provenance, (3) the rule that the Core +consumes `Evidence` **inline in its context** and never executes providers +itself, and (4) a tenant-scoped, declarative provider **registry** that selects +which adapters are active. + +Out of scope: the concrete adapter implementations and their vendor-specific +choices (each is delegated to a companion Platform ADR, e.g. a Node.js ADR for +the Lighthouse adapter), and the scorecard/gate products that consume the +resulting evidence (tracked separately). + +## Options Considered + +### Option A: The Core calls the tools directly + +Let `core-domain` invoke Lighthouse/TestSprite/etc. during evaluation. Rejected: +it breaks statelessness ([ADR-0101](./0101-core-stateless-evaluation-engine.md)), +puts network I/O and non-deterministic side-effects inside the deterministic +engine, and hard-couples the Core to specific tools. + +### Option B: One bespoke integration per tool at each surface + +Each surface (CLI, Portal, agent-runtime) wires each tool ad hoc. Rejected: N×M +drift, no shared normalization, inconsistent (or absent) provenance, and no way +to evaluate signals uniformly against policy. It also re-implements the +adapter/normalization work already established for the Port/Cortex and Jira +connectors. + +### Option C: Single provider port + canonical Evidence ACL + tenant registry (chosen) + +External producers implement one driven port and emit a normalized `Evidence` +object (an anti-corruption layer). The orchestration layer runs the *active* +providers, collects `Evidence[]`, and passes it inline to the Core. A +per-tenant registry declares which providers are active. Chosen: it keeps the +Core pure, makes every provider pluggable, tenant-selectable and disposable, and +reuses the connector-adapter pattern the suite already practices. + +## Decision and Rationale + +### 1. One driven port, owned by orchestration — not by the Core + +`IQualitySignalProvider` lives in the orchestration/application layer +(agent-runtime and the SDLC surfaces), **not** in `core-domain`. All provider +I/O — headless Chrome, cloud calls, LLM audits — happens behind this port. + +```ts +// orchestration layer (NOT core-domain) +interface IQualitySignalProvider { + readonly id: string; // "lighthouse" | "testsprite" | ... + supports(ctx: CollectionContext): boolean; + collect(target: CollectionTarget): Promise; +} +``` + +### 2. The Core knows only the canonical `Evidence` model + +`Evidence` is the sole surface the Core sees. It enters the `EvaluationContext` +**inline**, exactly as source files enter today via the repository-access / +`OverlayFileSystem` precedent ([ADR-0080](./0080-remote-repository-reference-contract.md), +[ADR-0101](./0101-core-stateless-evaluation-engine.md)). The Core is indifferent +to which tool produced a signal. + +```ts +// core-domain — the ONLY thing the Core imports +interface Evidence { + source: string; // opaque to the Core + dimension: string; // "performance" | "a11y" | "code-quality" | "testing" | ... + metrics: Record; + findings: Finding[]; + determinism: 'deterministic' | 'probabilistic'; // Lighthouse vs LLM-based + provenance: Provenance; // collectedBy, adapterVersion, artifactHash, timestamp +} +``` + +### 3. The Core never executes providers + +Collection is a side-effectful orchestration concern. The Core receives +already-collected `Evidence[]` and evaluates it against derived criteria and +policy. This preserves determinism and keeps the evaluator free of network and +vendor coupling. If a dimension has no evidence, the Core reports it as +`no-evidence`, never as a failure it caused. + +### 4. Providers are selected per tenant, declaratively + +A tenant-scoped registry (same spirit as the skill-registry SSOT and the +`.harness` manifest, honoring multi-tenant isolation — +[ADR-0010](./0010-multi-tenancy-architecture-strategy.md), +[ADR-0106](./0106-master-tenant-context-projections.md)) declares which providers +are active and their config. Selection is opt-in and lives in configuration, not +in the Core. + +```yaml +qualitySignals: + providers: + - { id: lighthouse, enabled: true, config: { categories: [performance, a11y, seo] } } + - { id: thermo-nuclear, enabled: true } + - { id: testsprite, enabled: false } # cloud/proprietary → opt-in, default off +``` + +### 5. Adapters live at the edge, boundary-enforced + +Concrete adapters live in `@evolith/infra-providers` (alongside the Port/Cortex +and Jira connectors), lazily imported so the package builds with none installed. +`lint:boundaries` forbids any third-party or adapter import from reaching +`core-domain`. Cloud/proprietary providers (e.g. TestSprite) isolate their code +egress at the adapter boundary and default to disabled. + +### 6. Provenance is mandatory and drives governance + +Every `Evidence` carries provenance (`collectedBy` / `adapterVersion` / +`artifactHash` / `timestamp`) and a `determinism` flag, so signals are +auditable ([ADR-0016](./0016-immutable-business-audit-trail.md)) and policy can +weight or gate on them (e.g. treat probabilistic evidence as advisory, require +deterministic evidence for a hard gate). + +## Evidence and Evaluation Criteria + +- **Statelessness preserved**: the Core imports only `Evidence`; grep must show + no provider/adapter import in `core-domain`. Same criterion applied to Hermes + in [ADR-0102](./0102-evolith-agent-runtime.md). +- **Precedent**: inline context ingestion already works for source files via the + repository-access model ([ADR-0080](./0080-remote-repository-reference-contract.md)); + `Evidence` follows the identical shape. +- **Reuse**: the driven-adapter pattern is proven by the Port/Cortex (GT-527) and + Jira (GT-529) connectors; this ADR generalizes it to evidence producers. +- **Enforceability**: the domain boundary is machine-checkable via + `lint:boundaries`. +- **Litmus test (Core-ADR)**: if Lighthouse, TestSprite, Claude SEO and the + thermo-nuclear rubric all disappeared tomorrow, the decision (port + canonical + Evidence + registry) still stands — they are illustrative adapters, not the + subject of the decision. + +## Consequences, Risks, and Trade-offs + +Positive: the Core stays pure and deterministic; any evidence producer becomes +pluggable, tenant-selectable and disposable; provenance makes every signal +auditable and policy-evaluable; the design/runtime conformance loop +([ADR-0104](./0104-topology-driven-advisory-design-governance.md)) closes with +real evidence. + +Negative / trade-offs: an extra indirection (collection → normalization → +evaluation); providers differ in determinism, so consumers must respect the +`determinism` flag rather than treating all evidence equally; probabilistic +(LLM-based) providers need a confidence/normalization discipline. Risks: adapter +or registry drift (mitigated by versioned adapters and an explicit registry) and +code egress for cloud providers (mitigated by adapter-boundary isolation and +default-off opt-in). No provider may ever be a hard dependency of the suite. + +## References + +- Lighthouse — runtime auditing engine (Apache-2.0), Node programmatic API with + JSON output: *(illustrative adapter)* +- TestSprite — autonomous AI testing; OSS CLI/MCP over a proprietary cloud + (credit-based): *(illustrative, opt-in adapter)* +- Claude SEO — MIT multi-agent audit skill pack (score + severity plan pattern): + *(pattern reference)* +- Thermo-nuclear code-quality review — structural review rubric: + + *(methodology reference)* + +## Related Decisions and Standards + +- [ADR-0101](./0101-core-stateless-evaluation-engine.md) — stateless Core + Evaluation Engine (the contract that consumes `Evidence`). +- [ADR-0102](./0102-evolith-agent-runtime.md) — ports & adapters agentic layer; + this ADR applies the same principle to evidence producers and reuses the + orchestration layer that runs the providers. +- [ADR-0104](./0104-topology-driven-advisory-design-governance.md) — derives the + criteria that this evidence confirms or refutes (the conformance loop). +- [ADR-0080](./0080-remote-repository-reference-contract.md) — inline context + ingestion precedent (`OverlayFileSystem`). +- [ADR-0010](./0010-multi-tenancy-architecture-strategy.md), + [ADR-0106](./0106-master-tenant-context-projections.md) — tenant isolation for + the per-tenant provider registry. +- [ADR-0016](./0016-immutable-business-audit-trail.md) — audit/provenance + guarantees for collected evidence. +- [core/ADR-0005](./0005-automated-sast-quality-gates.md), + [core/ADR-0018](./0018-testing-pyramid-quality-gates.md) — quality-gate + consumers of the evidence produced through this port. +- Companion Platform ADR (follow-on): Node.js adapter for the Lighthouse + provider — records the concrete vendor/runtime choice per the ADR authoring + standard. diff --git a/reference/core/architecture/adrs/core/README.es.md b/reference/core/architecture/adrs/core/README.es.md index ad4e246a3..cfd999413 100644 --- a/reference/core/architecture/adrs/core/README.es.md +++ b/reference/core/architecture/adrs/core/README.es.md @@ -87,6 +87,7 @@ * [0108-masstransit-owned-message-topology](./0108-masstransit-owned-message-topology.es.md) — **MassTransit es dueño de la topología de mensajes; los CRDs del broker son solo RBAC** * [0109-multi-project-satellite-governance](./0109-multi-project-satellite-governance.es.md) — **Gobernanza de satélites multi-proyecto (satélites monorepo); Core permanece soberano** * [0110-masstransit-v8-apache-license-pin](./0110-masstransit-v8-apache-license-pin.es.md) — **Permanecer en MassTransit v8 (Apache-2.0); v9 es comercial y no sublicenciable** +* [0111-quality-signal-provider-port](./0111-quality-signal-provider-port.es.md) — **Puerto de Proveedores de Señales de Calidad — la evidencia externa (Lighthouse, TestSprite, …) entra vía adaptadores y `Evidence` canónica; el Core nunca depende de ninguna herramienta** --- [Volver al Nivel Superior](../README.es.md) diff --git a/reference/core/architecture/adrs/core/README.md b/reference/core/architecture/adrs/core/README.md index d7eda7e71..c43c8a3b5 100644 --- a/reference/core/architecture/adrs/core/README.md +++ b/reference/core/architecture/adrs/core/README.md @@ -87,6 +87,7 @@ * [0108-masstransit-owned-message-topology](./0108-masstransit-owned-message-topology.md) — **MassTransit owns the message topology; broker CRDs are RBAC-only** * [0109-multi-project-satellite-governance](./0109-multi-project-satellite-governance.md) — **Multi-project satellite governance (monorepo satellites); Core stays sovereign** * [0110-masstransit-v8-apache-license-pin](./0110-masstransit-v8-apache-license-pin.md) — **Stay on MassTransit v8 (Apache-2.0); v9 is commercial and non-sublicensable** +* [0111-quality-signal-provider-port](./0111-quality-signal-provider-port.md) — **Quality Signal Provider port — external evidence (Lighthouse, TestSprite, …) enters via adapters and canonical `Evidence`; Core never depends on any tool** --- [Back to Upper Level](../README.md) diff --git a/reference/core/control-center/gaps/gap-reference-catalog.es.md b/reference/core/control-center/gaps/gap-reference-catalog.es.md index 0639cc3d4..35b0546b3 100644 --- a/reference/core/control-center/gaps/gap-reference-catalog.es.md +++ b/reference/core/control-center/gaps/gap-reference-catalog.es.md @@ -406,6 +406,97 @@ Este catálogo explica cada gap: problema, propósito, evidencia, criterios de c - **Dependencies:** none. - **Status:** `PENDING` +#### GT-533 + +**Title:** Puerto de Proveedores de Señales de Calidad + modelo canónico `Evidence` + registro por tenant (ADR-0111) + +- **Purpose:** Definir la única costura por la que cualquier herramienta externa de calidad/evidencia enriquece la evaluación del Core sin volverse dependencia del Core. +- **Evidence:** ADR-0111; el adaptador `ObservabilityEvidence` de GT-530 es una instancia concreta de la misma idea, pero no existe una costura de evidencia generalizada y seleccionable por tenant. +- **Impact:** Convierte a Evolith en el plano de control de gobernanza que normaliza la salida de cualquier auditor; cierra el lazo de conformidad diseño→runtime (ADR-0104) con evidencia real. +- **Risk:** Acoplar el Core determinista a herramientas volátiles, o integraciones a medida N×M, si no se respeta el puerto. +- **Affected files:** puerto `IQualitySignalProvider` en la capa de orquestación; tipos `Evidence`/`Provenance` en `core-domain` consumidos inline en `EvaluationContext`; config del registro de proveedores por tenant. +- **Component:** `Evolith Core` · **Dimension:** Architecture · **Type:** backend +- **Criticality:** P1 · **Complexity:** L +- **Proposed fix:** Puerto de salida propiedad de la orquestación; el Core importa solo `Evidence` (inline, como `OverlayFileSystem`, ADR-0080); el Core nunca ejecuta proveedores; registro declarativo opt-in por tenant; `provenance` + `determinism` obligatorios. +- **Acceptance criteria:** + - [ ] `core-domain` importa solo `Evidence` (grep limpio de imports de proveedor/adaptador). + - [ ] Los proveedores corren en orquestación; el Core evalúa `Evidence[]` recibida; evidencia ausente ⇒ `no-evidence`, no un fallo. + - [ ] El registro por tenant habilita/deshabilita proveedores de forma declarativa. +- **Dependencies:** ADR-0111; compone con GT-530. +- **Status:** `PENDING` + +#### GT-534 + +**Title:** Adaptador de referencia Lighthouse (Apache-2.0) + +- **Purpose:** Prueba prototype-first del puerto de Proveedores de Señales de Calidad: evidencia de runtime performance/a11y/SEO detrás de `IQualitySignalProvider`. +- **Evidence:** Lighthouse es OSS (Apache-2.0), maduro, con Node module embebible y salida JSON — la fuente de evidencia determinista de menor riesgo. +- **Impact:** Primera dimensión de evidencia real en un scorecard/gate; valida la costura end-to-end. +- **Risk:** Requiere Chrome headless + una URL desplegada (runtime, no design-time). +- **Affected files:** adaptador Lighthouse en `infra-providers`; ADR de Plataforma Node.js acompañante. +- **Component:** `infra-providers` · **Dimension:** Quality · **Type:** backend +- **Criticality:** P1 · **Complexity:** M +- **Proposed fix:** Adaptador que implementa `IQualitySignalProvider` sobre el Node module de Lighthouse, emitiendo `Evidence` determinista normalizada. +- **Acceptance criteria:** + - [ ] El adaptador emite `Evidence` normalizada con `determinism: 'deterministic'` y provenance completa. + - [ ] El ADR de Plataforma Node.js acompañante registra la elección de proveedor/runtime. +- **Dependencies:** GT-533. +- **Status:** `PENDING` + +#### GT-535 + +**Title:** Rúbrica de revisión estructural thermo-nuclear → agente de calidad de código + Quality Gate + +- **Purpose:** Adoptar una metodología estricta de revisión estructural como skill del agente code-quality-review y como criterio de regresión estructural del Quality Gate. +- **Evidence:** La rúbrica "thermo-nuclear" de Cursor (code-judo, disciplina de tamaño de archivo, chequeos de spaghetti/abstracción/capas, jerarquía de severidad) es una metodología probada; Evolith no tiene una rúbrica de revisión estructural explícita. +- **Impact:** Da al agente de calidad y al gate un estándar estructural explícito y auditable. +- **Risk:** Dependiente de LLM (evidencia probabilística); licencia/atribución de la rúbrica fuente. +- **Affected files:** skill code-quality-review de agent-runtime; rúbrica del Quality Gate. +- **Component:** `agent-runtime` · **Dimension:** Quality · **Type:** backend +- **Criticality:** P1 · **Complexity:** M +- **Proposed fix:** Codificar los siete estándares + jerarquía de severidad como skill y rúbrica de gate; emitir `Evidence` con `determinism: 'probabilistic'`. +- **Acceptance criteria:** + - [ ] El agente produce hallazgos estructurales ordenados por la jerarquía de severidad de la rúbrica. + - [ ] El gate puede tratar las regresiones estructurales como bloqueantes; atribución respetada. +- **Dependencies:** GT-533. +- **Status:** `PENDING` + +#### GT-536 + +**Title:** Adaptador de test-evidence TestSprite — opt-in, OFF por defecto + +- **Purpose:** Evidencia opcional de la dimensión testing detrás del puerto, sin ninguna dependencia dura de una nube propietaria. +- **Evidence:** El CLI/MCP de TestSprite son OSS pero el motor es una nube propietaria por créditos (egress de código); útil como señal opcional y como inspiración de pipeline (discover→plan→generate→execute→heal). +- **Impact:** Añade una dimensión de testing a los scorecards para tenants que hagan opt-in. +- **Risk:** Lock-in, coste por crédito, código saliendo del perímetro — mitigado por aislamiento en la frontera del adaptador y off por defecto. +- **Affected files:** adaptador TestSprite en `infra-providers` (deshabilitado por defecto en el registro). +- **Component:** `infra-providers` · **Dimension:** Testing · **Type:** backend +- **Criticality:** P2 · **Complexity:** M +- **Proposed fix:** Adaptador opt-in detrás de `IQualitySignalProvider`; egress aislado en la frontera; nunca dependencia de la suite. +- **Acceptance criteria:** + - [ ] El adaptador está deshabilitado por defecto y solo se activa con opt-in explícito por tenant. + - [ ] Ninguna ruta hace que el build/run de la suite dependa de TestSprite. +- **Dependencies:** GT-533. +- **Status:** `DEFERRED` + +#### GT-537 + +**Title:** Pack de Scorecards GEO / AI-discoverability (patrón Claude SEO) + +- **Purpose:** Pack opcional de Scorecards inspirado en la auditoría multi-agente de Claude SEO (score + plan por severidad). +- **Evidence:** Claude SEO (MIT) prueba que el patrón multi-agente→scorecard escala; SEO/GEO es adyacente al núcleo de gobernanza de arquitectura, así que pertenece a un pack de producto, no al Core. +- **Impact:** Dimensión opcional de valor en el plano Portal/Scorecards; valida el patrón que Evolith ya usa. +- **Risk:** Scope creep hacia el Core si no se mantiene como pack opcional. +- **Affected files:** pack Portal/Scorecards (fuera de `core-domain`). +- **Component:** `Tracker` · **Dimension:** Adoption · **Type:** backend +- **Criticality:** P3 · **Complexity:** L +- **Proposed fix:** Dimensión GEO/AI-discoverability como pack opcional de Scorecards, emitiendo `Evidence` vía el puerto; no es capacidad del Core. +- **Acceptance criteria:** + - [ ] El pack es opcional y no añade dependencia al Core. + - [ ] Produce un score + plan por severidad consistente con el modelo de scorecard. +- **Dependencies:** GT-533. +- **Status:** `DEFERRED` + --- ## 1. Detalle de Gaps diff --git a/reference/core/control-center/gaps/gap-reference-catalog.md b/reference/core/control-center/gaps/gap-reference-catalog.md index 108090c18..1f60e1eee 100644 --- a/reference/core/control-center/gaps/gap-reference-catalog.md +++ b/reference/core/control-center/gaps/gap-reference-catalog.md @@ -406,6 +406,97 @@ This catalog explains each gap: problem, purpose, evidence, closure criteria, an - **Dependencies:** none. - **Status:** `PENDING` +#### GT-533 + +**Title:** Quality Signal Provider port + canonical `Evidence` model + per-tenant registry (ADR-0111) + +- **Purpose:** Define the single seam through which any external quality/evidence tool enriches Core evaluation without becoming a dependency of the Core. +- **Evidence:** ADR-0111; the GT-530 `ObservabilityEvidence` adapter is a concrete instance of the same idea, but there is no generalized, tenant-selectable evidence seam. +- **Impact:** Turns Evolith into the governance control plane that normalizes any auditor's output; closes the design→runtime conformance loop (ADR-0104) with real evidence. +- **Risk:** Coupling the deterministic Core to volatile tools, or N×M bespoke integrations, if the port is not honored. +- **Affected files:** orchestration-layer `IQualitySignalProvider` port; `core-domain` `Evidence`/`Provenance` types consumed inline in `EvaluationContext`; per-tenant provider registry config. +- **Component:** `Evolith Core` · **Dimension:** Architecture · **Type:** backend +- **Criticality:** P1 · **Complexity:** L +- **Proposed fix:** Driven port owned by orchestration; Core imports only `Evidence` (inline, like `OverlayFileSystem`, ADR-0080); Core never executes providers; declarative opt-in registry per tenant; mandatory `provenance` + `determinism`. +- **Acceptance criteria:** + - [ ] `core-domain` imports only `Evidence` (grep-clean of provider/adapter imports). + - [ ] Providers run in orchestration; Core evaluates received `Evidence[]`; missing evidence ⇒ `no-evidence`, not a failure. + - [ ] Per-tenant registry enables/disables providers declaratively. +- **Dependencies:** ADR-0111; composes with GT-530. +- **Status:** `PENDING` + +#### GT-534 + +**Title:** Lighthouse reference adapter (Apache-2.0) + +- **Purpose:** Prototype-first proof of the Quality Signal Provider port: runtime performance/a11y/SEO evidence behind `IQualitySignalProvider`. +- **Evidence:** Lighthouse is OSS (Apache-2.0), mature, with an embeddable Node module and JSON output — the lowest-risk deterministic evidence source. +- **Impact:** First real evidence dimension in a scorecard/gate; validates the seam end-to-end. +- **Risk:** Requires headless Chrome + a deployed URL (runtime, not design-time). +- **Affected files:** `infra-providers` Lighthouse adapter; companion Node.js Platform ADR. +- **Component:** `infra-providers` · **Dimension:** Quality · **Type:** backend +- **Criticality:** P1 · **Complexity:** M +- **Proposed fix:** Adapter implementing `IQualitySignalProvider` over the Lighthouse Node module, emitting normalized deterministic `Evidence`. +- **Acceptance criteria:** + - [ ] Adapter emits normalized `Evidence` with `determinism: 'deterministic'` and full provenance. + - [ ] Companion Node.js Platform ADR records the vendor/runtime choice. +- **Dependencies:** GT-533. +- **Status:** `PENDING` + +#### GT-535 + +**Title:** Thermo-nuclear structural-review rubric → code-quality agent + Quality Gate + +- **Purpose:** Adopt a strict structural code-review methodology as a skill for the code-quality-review agent and as the structural-regression criteria of the Quality Gate. +- **Evidence:** The Cursor "thermo-nuclear" review rubric (code-judo, file-size discipline, spaghetti/abstraction/layering checks, severity hierarchy) is a proven methodology; Evolith has no explicit structural-review rubric. +- **Impact:** Gives the code-quality agent and the gate an explicit, auditable structural standard. +- **Risk:** LLM-dependent (probabilistic evidence); license/attribution of the source rubric. +- **Affected files:** agent-runtime code-quality-review skill; Quality Gate rubric. +- **Component:** `agent-runtime` · **Dimension:** Quality · **Type:** backend +- **Criticality:** P1 · **Complexity:** M +- **Proposed fix:** Encode the seven standards + severity hierarchy as a skill and gate rubric; emit `Evidence` with `determinism: 'probabilistic'`. +- **Acceptance criteria:** + - [ ] The agent produces structural findings ranked by the rubric's severity hierarchy. + - [ ] The gate can treat structural regressions as blocking; attribution respected. +- **Dependencies:** GT-533. +- **Status:** `PENDING` + +#### GT-536 + +**Title:** TestSprite test-evidence adapter — opt-in, default OFF + +- **Purpose:** Optional testing-dimension evidence behind the port, without any hard dependency on a proprietary cloud. +- **Evidence:** TestSprite's CLI/MCP are OSS but the engine is a credit-based proprietary cloud (code egress); useful as an optional signal and as pipeline inspiration (discover→plan→generate→execute→heal). +- **Impact:** Adds a testing dimension to scorecards for tenants who opt in. +- **Risk:** Lock-in, per-credit cost, code leaving the perimeter — mitigated by adapter-boundary isolation and default-off. +- **Affected files:** `infra-providers` TestSprite adapter (disabled by default in the registry). +- **Component:** `infra-providers` · **Dimension:** Testing · **Type:** backend +- **Criticality:** P2 · **Complexity:** M +- **Proposed fix:** Opt-in adapter behind `IQualitySignalProvider`; egress isolated at the boundary; never a suite dependency. +- **Acceptance criteria:** + - [ ] Adapter is disabled by default and only activates on explicit per-tenant opt-in. + - [ ] No code path makes the suite build/run depend on TestSprite. +- **Dependencies:** GT-533. +- **Status:** `DEFERRED` + +#### GT-537 + +**Title:** GEO / AI-discoverability Scorecards pack (Claude SEO pattern) + +- **Purpose:** Optional Scorecards pack inspired by the Claude SEO multi-agent audit (score + severity plan). +- **Evidence:** Claude SEO (MIT) proves the multi-agent→scorecard pattern scales; SEO/GEO is adjacent to the architecture-governance core, so it belongs in a product pack, not the Core. +- **Impact:** Optional value-add dimension in the Portal/Scorecards plane; validates the pattern Evolith already uses. +- **Risk:** Scope creep into the Core if not kept as an optional pack. +- **Affected files:** Portal/Scorecards pack (out of `core-domain`). +- **Component:** `Tracker` · **Dimension:** Adoption · **Type:** backend +- **Criticality:** P3 · **Complexity:** L +- **Proposed fix:** GEO/AI-discoverability dimension as an optional Scorecards pack, emitting `Evidence` via the port; not a Core capability. +- **Acceptance criteria:** + - [ ] The pack is optional and adds no Core dependency. + - [ ] Produces a score + severity plan consistent with the scorecard model. +- **Dependencies:** GT-533. +- **Status:** `DEFERRED` + --- ## 1. Gap Details diff --git a/reference/core/control-center/gaps/gap-tracking.es.md b/reference/core/control-center/gaps/gap-tracking.es.md index cfefad6f3..77c1d86bf 100644 --- a/reference/core/control-center/gaps/gap-tracking.es.md +++ b/reference/core/control-center/gaps/gap-tracking.es.md @@ -4,7 +4,7 @@ **Estado:** Seguimiento Activo **Responsable:** Evolith Architecture Board -**Última Actualización:** 2026-07-12 (GT-524…GT-532 — **Refuerzo de poder de Core (ejes 1 y 2 del análisis de posicionamiento)**: registradas 9 capacidades nuevas ordenadas por prioridad con las bases arquitectónicas comunes primero — base multi-lenguaje (GT-524 .NET/NetArchTest + GT-521 promovido DIFERIDO→PENDIENTE para PHP/Python/JVM), mapeo cross-cutting a compliance (GT-525), superficie de control edit-time (GT-526), conectores del wedge Port/Cortex/Backstage/Structurizr (GT-527/528, eje 2), e integraciones del surround Jira/Langfuse/Cowork/portafolio (GT-529…532, eje 1). Cada una traza a una § del doc `product/suite/positioning/evolith-strategic-positioning-comparative-landscape.md`. Previo 2026-07-11 (GT-511…GT-522 — Integración de Gobernanza de Arquitectura Ejecutable (A+B), lado Core: el motor de enforcers-OSS-por-CLI (modelo Violation, aprovisionamiento, IEnforcerAdapter/EnforcerEvaluator, adaptador dependency-cruiser, enforce:/PolicyCompiler, freezing, gate de PR/CI, paridad CLI/MCP/REST, MCP endurecido) + API de capabilities; enforcers diferidos y GraphQL opcional. Cada GT mapea a una etiqueta EAG-NN en el mapa unificado A/B; la mitad que aterriza en el Tracker vive en el tablero del Tracker. Previo 2026-07-09: Spike Fase-0b de ADR-0109 — **GT-474 HECHO**, bug de gobernanza en el CLI: `validate --core ` reportaba `warning` con `rulesChecked: 0` — no validaba NADA y no lo decía. Dos resolutores de rulesets discrepaban (`resolveRulesets` → `/src/rulesets` vs `DiskRulesetRepository` → `/rulesets`, ausente tras `apps/`→`src/`); el corpus vacío se blanqueaba en un `warning` por un `catch` genérico, y la ruta de aborto salía con 0. Fix: una lista de candidatos compartida por los tres resolutores, un `RulesetsNotFoundError` fatal ante raíz ausente **o** corpus de 0 reglas, cero reglas ⇒ `failed` bloqueante, todo aborto sale distinto de cero. `--core ` verifica ahora 105 reglas (antes 0). **GT-452 cerrado como sustituido.** — Ola de remediación de deuda de test — apendados GT-470…GT-473: 11 fallos preexistentes de core-domain + una suite de contrato que no corría, ANTERIORES al trabajo ADR-0109/DS-*. GT-470 error duro ante JSON malformado en disk-ruleset (HECHO `7e772d1c`); GT-471 resolución de módulos de la suite de contrato + fixtures REST/MCP obsoletas + fix mínimo de API ADR-0073 (34/34); GT-472 brecha de paridad native-OPA en el directorio ADR (GT-229) — path obsoleto `reference/architecture/adrs` en ambos handlers nativos + el constructor de input OPA; GT-473 `RULESET_ID_MAP` obsoleto (bug real) + base de gates del spec `validate-blueprint` (fixture obsoleta). Todos HECHO; core-domain 735/735, contrato 34/34. — Ola de gobernanza ADR-0109 Fase-0 — apendados GT-466…GT-469, el gate del cutover del monorepo: SVC-01 replanteada de repo-scope→project-scope + nueva SVC-06 de integridad de workspace (JSON de reglas + espejo OPA + input schema + handler nativo workspace-aware); schema `evolith.workspace.yaml` (`kind: SatelliteWorkspace`); `SatelliteRecord.subpath` + enumeración de workspace en el registro; `--satellite` unificado en validate/gate/phase/upgrade con resolución ancestro-más-cercano + fix del hardcode de cwd en `upgrade`. Todos HECHO; tests unitarios/paridad de core-domain + CLI en verde. — Registro de riesgos de la estrategia de despliegue (§15) — apendados GT-462…GT-465, los ítems de infra/messaging propiedad de Core desde `evolith-suite-deployment-strategy.md`: retirar CRDs Exchange/Queue/Binding de la ruta de mensajes (P0, §5.2), alertas de cola `_error` para mensajes veneno (P1, §5.3), dependencia del broker RabbitMQ compartido (P2, mitigado→DIFERIDO, §5.6), aplicación de NetworkPolicy con Cilium en kind (P2, §7). — 2026-07-04 Evaluación Camino-a-Producción — añadido épico GT-435 + GT-436…GT-446: re-versionado de paquetes (P0), CD del agent-runtime, cableado real de adapters/auth/observabilidad/HITL/secrets (P1), reliability/pen-test/reconciliación-docs (P2), y el piloto de producción del Tracker (cross-repo). Ordenados por estrategia de producción, organizados en dos milestones: GT-447 (Objetivo 1 — stack funcional en local con Docker/K8s, UI en URLs locales, refactor de diseño diferido a Fase 2) y GT-448 (Objetivo 2 — producción en la VPS con Coolify+K8s, UI incluida). — Épico de Design GT-425 — F1–F4 COMPLETADO: contratos `design` (5ddf4471), `designProfile`s de topología (46791e85), blueprint multi-concern CoC (0392fefe), evaluador `design` advisory (1b4e6f98), motor de recomendación de topología (0196b158). F6/GT-431 COMPLETADO: schema design-template + skills de colaboración + design-evaluate vía evaluate() + Core API POST /architecture/recommend-topology (4fcdc2c8); paridad CLI/MCP del recomendador como follow-on. F7/GT-432 COMPLETADO (33306d72). **F8/GT-433 COMPLETADO + GT-425 EPIC COMPLETO**: verificación E2E contra el corpus real + docs canónicos de la fase Design (d93bc0f2). El motor advisory de diseño funciona end-to-end y está expuesto. Follow-on restante: paridad CLI/MCP topology-recommend (tarea). GT-434 (épico de perfiles de artefactos downstream, espeja GT-425) EN-PROGRESO: `spec.phaseProfiles` en schema + 7 manifests (3fe3be23) + `PhaseArtifactProfileService` (fbf87b49) + endpoint Core API (221856b3) + phase-artifact-registry + E2E (6b1c5472). **GT-434 COMPLETADO.** Follow-on: `EvaluationKind` unificado `phase-artifacts` + paridad CLI/MCP (tarea).) +**Última Actualización:** 2026-07-13 (GT-533…GT-537 — **Evidencia externa vía adaptadores (ADR-0111)**: registrada la ola de ingesta de evidencia que operacionaliza el puerto de Proveedores de Señales de Calidad — el puerto fundacional + modelo canónico `Evidence` + registro por tenant (GT-533), el adaptador de referencia Lighthouse como prueba prototype-first (GT-534, ALTA), la rúbrica de revisión estructural thermo-nuclear integrada en el agente de calidad de código + Quality Gate (GT-535, ALTA), un adaptador de test-evidence de TestSprite opt-in y off-por-defecto (GT-536, MEDIA-BAJA), y un pack de Scorecards GEO/AI-discoverability inspirado en el patrón multi-agente de Claude SEO (GT-537, diferido). Generaliza el adaptador `ObservabilityEvidence` de GT-530 en una única costura uniforme; ninguna herramienta externa es jamás dependencia del Core. Previo 2026-07-12 (GT-524…GT-532 — **Refuerzo de poder de Core (ejes 1 y 2 del análisis de posicionamiento)**: registradas 9 capacidades nuevas ordenadas por prioridad con las bases arquitectónicas comunes primero — base multi-lenguaje (GT-524 .NET/NetArchTest + GT-521 promovido DIFERIDO→PENDIENTE para PHP/Python/JVM), mapeo cross-cutting a compliance (GT-525), superficie de control edit-time (GT-526), conectores del wedge Port/Cortex/Backstage/Structurizr (GT-527/528, eje 2), e integraciones del surround Jira/Langfuse/Cowork/portafolio (GT-529…532, eje 1). Cada una traza a una § del doc `product/suite/positioning/evolith-strategic-positioning-comparative-landscape.md`. Previo 2026-07-11 (GT-511…GT-522 — Integración de Gobernanza de Arquitectura Ejecutable (A+B), lado Core: el motor de enforcers-OSS-por-CLI (modelo Violation, aprovisionamiento, IEnforcerAdapter/EnforcerEvaluator, adaptador dependency-cruiser, enforce:/PolicyCompiler, freezing, gate de PR/CI, paridad CLI/MCP/REST, MCP endurecido) + API de capabilities; enforcers diferidos y GraphQL opcional. Cada GT mapea a una etiqueta EAG-NN en el mapa unificado A/B; la mitad que aterriza en el Tracker vive en el tablero del Tracker. Previo 2026-07-09: Spike Fase-0b de ADR-0109 — **GT-474 HECHO**, bug de gobernanza en el CLI: `validate --core ` reportaba `warning` con `rulesChecked: 0` — no validaba NADA y no lo decía. Dos resolutores de rulesets discrepaban (`resolveRulesets` → `/src/rulesets` vs `DiskRulesetRepository` → `/rulesets`, ausente tras `apps/`→`src/`); el corpus vacío se blanqueaba en un `warning` por un `catch` genérico, y la ruta de aborto salía con 0. Fix: una lista de candidatos compartida por los tres resolutores, un `RulesetsNotFoundError` fatal ante raíz ausente **o** corpus de 0 reglas, cero reglas ⇒ `failed` bloqueante, todo aborto sale distinto de cero. `--core ` verifica ahora 105 reglas (antes 0). **GT-452 cerrado como sustituido.** — Ola de remediación de deuda de test — apendados GT-470…GT-473: 11 fallos preexistentes de core-domain + una suite de contrato que no corría, ANTERIORES al trabajo ADR-0109/DS-*. GT-470 error duro ante JSON malformado en disk-ruleset (HECHO `7e772d1c`); GT-471 resolución de módulos de la suite de contrato + fixtures REST/MCP obsoletas + fix mínimo de API ADR-0073 (34/34); GT-472 brecha de paridad native-OPA en el directorio ADR (GT-229) — path obsoleto `reference/architecture/adrs` en ambos handlers nativos + el constructor de input OPA; GT-473 `RULESET_ID_MAP` obsoleto (bug real) + base de gates del spec `validate-blueprint` (fixture obsoleta). Todos HECHO; core-domain 735/735, contrato 34/34. — Ola de gobernanza ADR-0109 Fase-0 — apendados GT-466…GT-469, el gate del cutover del monorepo: SVC-01 replanteada de repo-scope→project-scope + nueva SVC-06 de integridad de workspace (JSON de reglas + espejo OPA + input schema + handler nativo workspace-aware); schema `evolith.workspace.yaml` (`kind: SatelliteWorkspace`); `SatelliteRecord.subpath` + enumeración de workspace en el registro; `--satellite` unificado en validate/gate/phase/upgrade con resolución ancestro-más-cercano + fix del hardcode de cwd en `upgrade`. Todos HECHO; tests unitarios/paridad de core-domain + CLI en verde. — Registro de riesgos de la estrategia de despliegue (§15) — apendados GT-462…GT-465, los ítems de infra/messaging propiedad de Core desde `evolith-suite-deployment-strategy.md`: retirar CRDs Exchange/Queue/Binding de la ruta de mensajes (P0, §5.2), alertas de cola `_error` para mensajes veneno (P1, §5.3), dependencia del broker RabbitMQ compartido (P2, mitigado→DIFERIDO, §5.6), aplicación de NetworkPolicy con Cilium en kind (P2, §7). — 2026-07-04 Evaluación Camino-a-Producción — añadido épico GT-435 + GT-436…GT-446: re-versionado de paquetes (P0), CD del agent-runtime, cableado real de adapters/auth/observabilidad/HITL/secrets (P1), reliability/pen-test/reconciliación-docs (P2), y el piloto de producción del Tracker (cross-repo). Ordenados por estrategia de producción, organizados en dos milestones: GT-447 (Objetivo 1 — stack funcional en local con Docker/K8s, UI en URLs locales, refactor de diseño diferido a Fase 2) y GT-448 (Objetivo 2 — producción en la VPS con Coolify+K8s, UI incluida). — Épico de Design GT-425 — F1–F4 COMPLETADO: contratos `design` (5ddf4471), `designProfile`s de topología (46791e85), blueprint multi-concern CoC (0392fefe), evaluador `design` advisory (1b4e6f98), motor de recomendación de topología (0196b158). F6/GT-431 COMPLETADO: schema design-template + skills de colaboración + design-evaluate vía evaluate() + Core API POST /architecture/recommend-topology (4fcdc2c8); paridad CLI/MCP del recomendador como follow-on. F7/GT-432 COMPLETADO (33306d72). **F8/GT-433 COMPLETADO + GT-425 EPIC COMPLETO**: verificación E2E contra el corpus real + docs canónicos de la fase Design (d93bc0f2). El motor advisory de diseño funciona end-to-end y está expuesto. Follow-on restante: paridad CLI/MCP topology-recommend (tarea). GT-434 (épico de perfiles de artefactos downstream, espeja GT-425) EN-PROGRESO: `spec.phaseProfiles` en schema + 7 manifests (3fe3be23) + `PhaseArtifactProfileService` (fbf87b49) + endpoint Core API (221856b3) + phase-artifact-registry + E2E (6b1c5472). **GT-434 COMPLETADO.** Follow-on: `EvaluationKind` unificado `phase-artifacts` + paridad CLI/MCP (tarea).) **Detalle de Gaps:** [Catálogo de Referencia de Gaps](./gap-reference-catalog.es.md) Este tablero es la única fuente de verdad para deuda técnica, gaps, oportunidades, habilitadores, prioridad y estado. Selecciona un ID para abrir la descripción del problema, propósito, evidencia, criterios de cierre y referencias. @@ -37,6 +37,11 @@ Este tablero es la única fuente de verdad para deuda técnica, gaps, oportunida | [`GT-530`](./gap-reference-catalog.es.md#gt-530) | **[Surround · eje 1] Adaptador Langfuse → evidencia canónica.** Mapear traces/evaluaciones/costo/latencia/versión-de-prompt/tool-calls de Langfuse al modelo de evidencia de Evolith, para no reconstruir una plataforma de telemetría LLM. §8.1 / §12. Fix: `LangfuseEvidenceAdapter` vía puerto de observabilidad. **EN-PROGRESO (`domain/observability-evidence.ts`):** aterrizó el mapper puro + forma portable — `ObservabilityEvidence` (traceId/model/promptVersion/costUsd/latencyMs/totalTokens/toolCalls/evaluations/url, provider-neutral §9-5), `mapLangfuseTrace` (agrega costo/tokens/latencia de las observaciones, toma model/prompt de la 1ª GENERATION, colecta tool-calls distintos, mapea scores→evaluations; trace sin id⇒null) y el puerto `IObservabilityEvidenceSource`. Verificado: core-domain 945/945 (+6), tsc limpio. **Pendiente (conector/infra):** el fetch read-only de la Langfuse API detrás del puerto. **COMPLETADO (`wave`):** `LangfuseEvidenceAdapter implements IObservabilityEvidenceSource` sobre un `LangfuseHttpClient` inyectado, delegando en `mapLangfuseTrace`. Verificado: infra-providers 78/78. | `Evolith Core` | Cross | P2 | L | `COMPLETADO` | | [`GT-531`](./gap-reference-catalog.es.md#gt-531) | **[Surround · eje 1] Adaptador Cowork/Claude como ejecutor gobernado acotado.** Ejecutor de actividades con permisos/planes/aprobaciones/captura de evidencia, tratando a Claude como uno de varios ejecutores reemplazables (§8.2, §9). Extiende el épico agent-runtime GT-383…394 (HITL GT-441 / adapters GT-438). **EN-PROGRESO (`cowork-agent.adapter.ts`):** aterrizó el `CoworkAgentEngineAdapter` — implementa el mismo `IAgentEnginePort` que stub/hermes/swarms (Claude Cowork como ejecutor **reemplazable**), y es **acotado**: nunca propone una herramienta fuera del catálogo de skills gobernado (una propuesta de Cowork/LLM a una capacidad inexistente se rechaza en vez de inventarse). El envelope del runtime (approval GT-441 / policy / trace) ya lo gobierna; la llamada viva a Claude va detrás de `CoworkClient` inyectable (sin cliente = determinista, como el stub). Verificado: agent-runtime 92/92, tsc limpio, surface-freeze GT-388 actualizado. **Pendiente (conector/infra):** el `CoworkClient` real contra la Claude/Cowork API. | `agent-runtime` | Cross | P2 | M | `EN-PROGRESO` | | [`GT-532`](./gap-reference-catalog.es.md#gt-532) | **[Surround · eje 1] Vistas ejecutivas de portafolio + adaptadores marketplace + paquetes de gobernanza por tenant.** Mejora de adopción empresarial y escala de ecosistema (§12 P2); mayormente Tracker (plano de captura de valor enterprise). | `Tracker` | Cross | P3 | XL | `PENDIENTE` | +| [`GT-533`](./gap-reference-catalog.es.md#gt-533) | **[Evidencia · ADR-0111] Puerto de Proveedores de Señales de Calidad + modelo canónico `Evidence` + registro por tenant.** La costura por la que cualquier herramienta externa de calidad/evidencia enriquece al Core sin volverse dependencia: puerto de salida `IQualitySignalProvider` propiedad de la orquestación (nunca `core-domain`); el Core importa solo `Evidence` y la recibe inline (como los archivos fuente vía `OverlayFileSystem`, ADR-0080); el Core nunca ejecuta proveedores; registro declarativo opt-in por tenant; `provenance` + flag `determinism` obligatorios. Generaliza el adaptador `ObservabilityEvidence` de GT-530 en una única costura. **Prototipar primero.** | `Evolith Core` | Cross | P1 | L | `PENDIENTE` | +| [`GT-534`](./gap-reference-catalog.es.md#gt-534) | **[Adaptador de evidencia · ALTA] Adaptador de referencia Lighthouse (Apache-2.0).** Evidencia de runtime (performance/a11y/SEO, determinista) detrás de `IQualitySignalProvider`; la prueba prototype-first del puerto. OSS, Node module embebible con salida JSON, sin lock-in. Requiere un ADR de Plataforma Node.js acompañante para la elección concreta de proveedor/runtime. | `infra-providers` | Cross | P1 | M | `PENDIENTE` | +| [`GT-535`](./gap-reference-catalog.es.md#gt-535) | **[Quality gate · ALTA] Rúbrica de revisión estructural thermo-nuclear → agente de calidad de código + Quality Gate.** Adoptar la metodología de revisión estructural estricta (code-judo, disciplina de tamaño de archivo, chequeos de spaghetti/abstracción/capas, jerarquía de severidad) como skill del agente code-quality-review y como criterio de regresión estructural del Quality Gate. Metodología de referencia, sin dependencia de runtime; respetar atribución/licencia de la fuente. | `agent-runtime` | Cross | P1 | M | `PENDIENTE` | +| [`GT-536`](./gap-reference-catalog.es.md#gt-536) | **[Adaptador de evidencia · opt-in] Adaptador de test-evidence TestSprite — OFF por defecto.** Evidencia opcional de la dimensión testing detrás del puerto; nube propietaria + coste por crédito + egress de código aislado en la frontera del adaptador; **nunca dependencia dura** (opt-in, deshabilitado por defecto). Referenciar el pipeline discover→plan→generate→execute→heal para el agente autónomo de remediación, sin depender de su nube. | `infra-providers` | Cross | P2 | M | `DIFERIDO` | +| [`GT-537`](./gap-reference-catalog.es.md#gt-537) | **[Pack de Scorecards] Dimensión GEO / AI-discoverability (patrón Claude SEO).** Pack opcional de Scorecards inspirado en la auditoría multi-agente de Claude SEO (score + plan por severidad); valida que el patrón multi-agente→scorecard escala. No es capacidad del Core — un pack de producto en el plano Portal/Scorecards. | `Tracker` | Cross | P3 | L | `DIFERIDO` | | [`GT-486`](./gap-reference-catalog.es.md#gt-486) | **el CLI no emitió un envelope ADR-0073 parseable para sdlc-status.** La salida no pudo parsearse en un envelope { success, data\|error, meta }. (Auto-detectado por el agente de pruebas exploratorias en la operación `sdlc-status`.) | `Evolith CLI` | Cross | P2 | S | `COMPLETADO` | | [`GT-487`](./gap-reference-catalog.es.md#gt-487) | **el CLI no emitió un envelope ADR-0073 parseable para sdlc-handoff.** La salida no pudo parsearse en un envelope { success, data\|error, meta }. (Auto-detectado por el agente de pruebas exploratorias en la operación `sdlc-handoff`.) | `Evolith CLI` | Cross | P2 | S | `COMPLETADO` | | [`GT-490`](./gap-reference-catalog.es.md#gt-490) | **el CLI no emitió un envelope ADR-0073 parseable para sdlc-generate.** La salida no pudo parsearse en un envelope { success, data\|error, meta }. (Auto-detectado por el agente de pruebas exploratorias en la operación `sdlc-generate`.) | `Evolith CLI` | Cross | P2 | S | `COMPLETADO` | diff --git a/reference/core/control-center/gaps/gap-tracking.md b/reference/core/control-center/gaps/gap-tracking.md index df4f7eb20..5e292cf1e 100644 --- a/reference/core/control-center/gaps/gap-tracking.md +++ b/reference/core/control-center/gaps/gap-tracking.md @@ -4,7 +4,7 @@ **Status:** Active Tracking **Owner:** Evolith Architecture Board -**Last Updated:** 2026-07-12 (GT-524…GT-532 — **Core power reinforcement (axes 1 and 2 of the positioning analysis)**: registered 9 new capabilities ordered by priority with the common architectural bases first — multi-language base (GT-524 .NET/NetArchTest + GT-521 promoted DEFERRED→PENDING for PHP/Python/JVM), cross-cutting compliance mapping (GT-525), edit-time control surface (GT-526), wedge connectors Port/Cortex/Backstage/Structurizr (GT-527/528, axis 2), and surround integrations Jira/Langfuse/Cowork/portfolio (GT-529…532, axis 1). Each traces to a § of `product/suite/positioning/evolith-strategic-positioning-comparative-landscape.md`. Previous 2026-07-11 (GT-511…GT-522 — Executable Architecture Governance Integration (A+B), Core-side: the OSS-enforcers-by-CLI engine (Violation model, provisioning, IEnforcerAdapter/EnforcerEvaluator, dependency-cruiser adapter, enforce:/PolicyCompiler, freezing, PR/CI gate, CLI/MCP/REST parity, hardened MCP) + capabilities API; deferred enforcers & optional GraphQL. Each GT maps to an EAG-NN label in the unified A/B map; the Tracker-landing half lives in the Tracker board. Previous 2026-07-09: ADR-0109 Phase-0b spike — **GT-474 DONE**, a governance bug in the CLI: `validate --core ` reported `warning` with `rulesChecked: 0` — it validated NOTHING and did not say so. Two ruleset resolvers disagreed (`resolveRulesets` → `/src/rulesets` vs `DiskRulesetRepository` → `/rulesets`, absent post `apps/`→`src/`); the empty corpus was then laundered into a `warning` by a blanket `catch`, and the abort path exited 0. Fix: one shared candidate list across all three resolvers, a fatal `RulesetsNotFoundError` on a missing root **or** a 0-rule corpus, zero rules ⇒ blocking `failed`, every abort exits non-zero. `--core ` now checks 105 rules (was 0). **GT-452 closed as superseded.** — Test-debt remediation wave — appended GT-470…GT-473: 11 pre-existing core-domain failures + a non-running contract suite that PREDATE the ADR-0109/DS-* work. GT-470 disk-ruleset malformed-JSON hard error (DONE `7e772d1c`); GT-471 contract-suite module resolution + stale REST/MCP fixtures + minimal ADR-0073 API fix (34/34); GT-472 native-OPA ADR-directory parity gap (GT-229) — stale `reference/architecture/adrs` path in both native handlers + the OPA input-builder; GT-473 stale `RULESET_ID_MAP` (real bug) + `validate-blueprint` spec gate base (stale fixture). All DONE; core-domain 735/735, contract 34/34. — ADR-0109 Phase-0 governance wave — appended GT-466…GT-469, the monorepo-cutover gate: SVC-01 reframed repo-scoped→project-scoped + new SVC-06 workspace integrity (rules JSON + OPA mirror + input schema + workspace-aware native handler); `evolith.workspace.yaml` schema (`kind: SatelliteWorkspace`); `SatelliteRecord.subpath` + registry workspace enumeration; CLI `--satellite` unified across validate/gate/phase/upgrade with nearest-ancestor resolution + `upgrade` cwd-hardcode fix. All DONE; core-domain + CLI unit/parity tests green. — Deployment-strategy risk register (§15) — appended GT-462…GT-465, the Core-owned infra/messaging items from `evolith-suite-deployment-strategy.md`: retire message-path Exchange/Queue/Binding CRDs (P0, §5.2), poison-message `_error`-queue alerts (P1, §5.3), shared RabbitMQ broker dependency (P2, mitigated→DEFERRED, §5.6), Cilium-on-kind NetworkPolicy enforcement (P2, §7). — 2026-07-04 Road-to-Production assessment — added epic GT-435 + GT-436…GT-446: package re-versioning (P0), CD for agent-runtime, real adapter/auth/observability/HITL/secrets wiring (P1), reliability/pen-test/doc-reconcile (P2), and the Tracker production pilot (cross-repo). Ordered by production strategy, organized under two milestones: GT-447 (Objective 1 — full stack functional locally in Docker/K8s, UI on local URLs, design refactor deferred to Phase 2) and GT-448 (Objective 2 — production on the VPS with Coolify+K8s, UI included). — Design-phase epic GT-425 — F1–F4 DONE: `design` contracts (5ddf4471), topology `designProfile`s (46791e85), blueprint multi-concern CoC (0392fefe), advisory `design` evaluator (1b4e6f98), topology recommendation engine (0196b158). F6/GT-431 DONE: design-template schema + collaboration skills + design-evaluate via evaluate() + Core API POST /architecture/recommend-topology (4fcdc2c8); CLI/MCP recommend parity tracked as a follow-on. F7/GT-432 DONE (33306d72). **F8/GT-433 DONE + GT-425 EPIC COMPLETE**: E2E verification against the real corpus + canonical Design-phase docs (d93bc0f2). The advisory design engine is functional end-to-end and exposed. Remaining follow-on: CLI/MCP topology-recommend parity (task). GT-434 (downstream phase artifact profiles epic, mirrors GT-425) IN-PROGRESS: `spec.phaseProfiles` in schema + 7 manifests (3fe3be23) + `PhaseArtifactProfileService` (fbf87b49) + Core API endpoint (221856b3) + phase-artifact-registry + E2E (6b1c5472). **GT-434 DONE.** Follow-on: unified `phase-artifacts` EvaluationKind + CLI/MCP parity (task).) +**Last Updated:** 2026-07-13 (GT-533…GT-537 — **External evidence via adapters (ADR-0111)**: registered the evidence-ingestion wave that operationalizes the Quality Signal Provider port — the foundational port + canonical `Evidence` model + per-tenant registry (GT-533), the Lighthouse reference adapter as the prototype-first proof (GT-534, HIGH), the thermo-nuclear structural-review rubric folded into the code-quality agent + Quality Gate (GT-535, HIGH), an opt-in default-off TestSprite test-evidence adapter (GT-536, MED-LOW), and a GEO/AI-discoverability Scorecards pack inspired by the Claude SEO multi-agent pattern (GT-537, deferred). Generalizes the GT-530 `ObservabilityEvidence` adapter into one uniform seam; no external tool is ever a Core dependency. Previous 2026-07-12 (GT-524…GT-532 — **Core power reinforcement (axes 1 and 2 of the positioning analysis)**: registered 9 new capabilities ordered by priority with the common architectural bases first — multi-language base (GT-524 .NET/NetArchTest + GT-521 promoted DEFERRED→PENDING for PHP/Python/JVM), cross-cutting compliance mapping (GT-525), edit-time control surface (GT-526), wedge connectors Port/Cortex/Backstage/Structurizr (GT-527/528, axis 2), and surround integrations Jira/Langfuse/Cowork/portfolio (GT-529…532, axis 1). Each traces to a § of `product/suite/positioning/evolith-strategic-positioning-comparative-landscape.md`. Previous 2026-07-11 (GT-511…GT-522 — Executable Architecture Governance Integration (A+B), Core-side: the OSS-enforcers-by-CLI engine (Violation model, provisioning, IEnforcerAdapter/EnforcerEvaluator, dependency-cruiser adapter, enforce:/PolicyCompiler, freezing, PR/CI gate, CLI/MCP/REST parity, hardened MCP) + capabilities API; deferred enforcers & optional GraphQL. Each GT maps to an EAG-NN label in the unified A/B map; the Tracker-landing half lives in the Tracker board. Previous 2026-07-09: ADR-0109 Phase-0b spike — **GT-474 DONE**, a governance bug in the CLI: `validate --core ` reported `warning` with `rulesChecked: 0` — it validated NOTHING and did not say so. Two ruleset resolvers disagreed (`resolveRulesets` → `/src/rulesets` vs `DiskRulesetRepository` → `/rulesets`, absent post `apps/`→`src/`); the empty corpus was then laundered into a `warning` by a blanket `catch`, and the abort path exited 0. Fix: one shared candidate list across all three resolvers, a fatal `RulesetsNotFoundError` on a missing root **or** a 0-rule corpus, zero rules ⇒ blocking `failed`, every abort exits non-zero. `--core ` now checks 105 rules (was 0). **GT-452 closed as superseded.** — Test-debt remediation wave — appended GT-470…GT-473: 11 pre-existing core-domain failures + a non-running contract suite that PREDATE the ADR-0109/DS-* work. GT-470 disk-ruleset malformed-JSON hard error (DONE `7e772d1c`); GT-471 contract-suite module resolution + stale REST/MCP fixtures + minimal ADR-0073 API fix (34/34); GT-472 native-OPA ADR-directory parity gap (GT-229) — stale `reference/architecture/adrs` path in both native handlers + the OPA input-builder; GT-473 stale `RULESET_ID_MAP` (real bug) + `validate-blueprint` spec gate base (stale fixture). All DONE; core-domain 735/735, contract 34/34. — ADR-0109 Phase-0 governance wave — appended GT-466…GT-469, the monorepo-cutover gate: SVC-01 reframed repo-scoped→project-scoped + new SVC-06 workspace integrity (rules JSON + OPA mirror + input schema + workspace-aware native handler); `evolith.workspace.yaml` schema (`kind: SatelliteWorkspace`); `SatelliteRecord.subpath` + registry workspace enumeration; CLI `--satellite` unified across validate/gate/phase/upgrade with nearest-ancestor resolution + `upgrade` cwd-hardcode fix. All DONE; core-domain + CLI unit/parity tests green. — Deployment-strategy risk register (§15) — appended GT-462…GT-465, the Core-owned infra/messaging items from `evolith-suite-deployment-strategy.md`: retire message-path Exchange/Queue/Binding CRDs (P0, §5.2), poison-message `_error`-queue alerts (P1, §5.3), shared RabbitMQ broker dependency (P2, mitigated→DEFERRED, §5.6), Cilium-on-kind NetworkPolicy enforcement (P2, §7). — 2026-07-04 Road-to-Production assessment — added epic GT-435 + GT-436…GT-446: package re-versioning (P0), CD for agent-runtime, real adapter/auth/observability/HITL/secrets wiring (P1), reliability/pen-test/doc-reconcile (P2), and the Tracker production pilot (cross-repo). Ordered by production strategy, organized under two milestones: GT-447 (Objective 1 — full stack functional locally in Docker/K8s, UI on local URLs, design refactor deferred to Phase 2) and GT-448 (Objective 2 — production on the VPS with Coolify+K8s, UI included). — Design-phase epic GT-425 — F1–F4 DONE: `design` contracts (5ddf4471), topology `designProfile`s (46791e85), blueprint multi-concern CoC (0392fefe), advisory `design` evaluator (1b4e6f98), topology recommendation engine (0196b158). F6/GT-431 DONE: design-template schema + collaboration skills + design-evaluate via evaluate() + Core API POST /architecture/recommend-topology (4fcdc2c8); CLI/MCP recommend parity tracked as a follow-on. F7/GT-432 DONE (33306d72). **F8/GT-433 DONE + GT-425 EPIC COMPLETE**: E2E verification against the real corpus + canonical Design-phase docs (d93bc0f2). The advisory design engine is functional end-to-end and exposed. Remaining follow-on: CLI/MCP topology-recommend parity (task). GT-434 (downstream phase artifact profiles epic, mirrors GT-425) IN-PROGRESS: `spec.phaseProfiles` in schema + 7 manifests (3fe3be23) + `PhaseArtifactProfileService` (fbf87b49) + Core API endpoint (221856b3) + phase-artifact-registry + E2E (6b1c5472). **GT-434 DONE.** Follow-on: unified `phase-artifacts` EvaluationKind + CLI/MCP parity (task).) **Gap Details:** [Gap Reference Catalog](./gap-reference-catalog.md) This board is the single source of truth for technical debt, gaps, opportunities, enablers, priority, and status. Select a gap ID to open its problem statement, purpose, evidence, closure criteria, and references. @@ -37,6 +37,11 @@ This board is the single source of truth for technical debt, gaps, opportunities | [`GT-530`](./gap-reference-catalog.md#gt-530) | **[Surround · axis 1] Langfuse adapter → canonical evidence.** Map Langfuse traces/evaluations/cost/latency/prompt-version/tool-calls to Evolith's evidence model, to avoid rebuilding an LLM telemetry platform. §8.1 / §12. Fix: `LangfuseEvidenceAdapter` via the observability port. **IN-PROGRESS (`domain/observability-evidence.ts`):** landed the pure mapper + portable shape — `ObservabilityEvidence` (traceId/model/promptVersion/costUsd/latencyMs/totalTokens/toolCalls/evaluations/url, provider-neutral §9-5), `mapLangfuseTrace` (aggregates cost/tokens/latency across observations, takes model/prompt from the first GENERATION, collects distinct tool-calls, maps scores→evaluations; a trace with no id⇒null) and the `IObservabilityEvidenceSource` port. Verified: core-domain 945/945 (+6), tsc clean. **Remaining (connector/infra):** the read-only Langfuse API fetch behind the port. **DONE (`wave`):** `LangfuseEvidenceAdapter implements IObservabilityEvidenceSource` over an injected `LangfuseHttpClient`, delegating to `mapLangfuseTrace`. Verified: infra-providers 78/78. | `Evolith Core` | Cross | P2 | L | `DONE` | | [`GT-531`](./gap-reference-catalog.md#gt-531) | **[Surround · axis 1] Cowork/Claude adapter as a bounded governed executor.** Activity executor with permissions/plans/approvals/evidence capture, treating Claude as one of several replaceable executors (§8.2, §9). Extends the agent-runtime epic GT-383…394 (HITL GT-441 / adapters GT-438). **IN-PROGRESS (`cowork-agent.adapter.ts`):** landed `CoworkAgentEngineAdapter` — implements the same `IAgentEnginePort` as stub/hermes/swarms (Claude Cowork as a **replaceable** executor), and is **bounded**: it never proposes a tool outside the governed skill catalog (a Cowork/LLM proposal for a non-existent capability is rejected, not invented). The runtime envelope (approval GT-441 / policy / trace) already governs it; the live Claude call sits behind an injectable `CoworkClient` (no client = deterministic, like the stub). Verified: agent-runtime 92/92, tsc clean, GT-388 surface-freeze updated. **Remaining (connector/infra):** the real `CoworkClient` against the Claude/Cowork API. | `agent-runtime` | Cross | P2 | M | `IN-PROGRESS` | | [`GT-532`](./gap-reference-catalog.md#gt-532) | **[Surround · axis 1] Executive portfolio views + marketplace adapters + per-tenant governance packages.** Enterprise-adoption and ecosystem-scale improvement (§12 P2); mostly Tracker (enterprise value-capture plane). | `Tracker` | Cross | P3 | XL | `PENDING` | +| [`GT-533`](./gap-reference-catalog.md#gt-533) | **[Evidence · ADR-0111] Quality Signal Provider port + canonical `Evidence` model + per-tenant registry.** The seam through which any external quality/evidence tool enriches the Core without becoming a dependency: driven port `IQualitySignalProvider` owned by orchestration (never `core-domain`); Core imports only `Evidence` and receives it inline (like source files via `OverlayFileSystem`, ADR-0080); Core never executes providers; declarative opt-in registry per tenant; mandatory `provenance` + `determinism` flag. Generalizes the GT-530 `ObservabilityEvidence` adapter into one uniform seam. **Prototype first.** | `Evolith Core` | Cross | P1 | L | `PENDING` | +| [`GT-534`](./gap-reference-catalog.md#gt-534) | **[Evidence adapter · HIGH] Lighthouse reference adapter (Apache-2.0).** Runtime evidence (performance/a11y/SEO, deterministic) behind `IQualitySignalProvider`; the prototype-first proof of the port. OSS, embeddable Node module with JSON output, no lock-in. Needs a companion Node.js Platform ADR for the concrete vendor/runtime choice. | `infra-providers` | Cross | P1 | M | `PENDING` | +| [`GT-535`](./gap-reference-catalog.md#gt-535) | **[Quality gate · HIGH] Thermo-nuclear structural-review rubric → code-quality agent + Quality Gate.** Adopt the strict structural-review methodology (code-judo, file-size discipline, spaghetti/abstraction/layering checks, severity hierarchy) as a skill for the code-quality-review agent and as the structural-regression criteria of the Quality Gate. Reference methodology, no runtime dependency; respect source attribution/license. | `agent-runtime` | Cross | P1 | M | `PENDING` | +| [`GT-536`](./gap-reference-catalog.md#gt-536) | **[Evidence adapter · opt-in] TestSprite test-evidence adapter — default OFF.** Optional testing-dimension evidence behind the port; proprietary cloud + credit cost + code egress isolated at the adapter boundary; **never a hard dependency** (opt-in, disabled by default). Reference the discover→plan→generate→execute→heal pipeline for the autonomous remediation agent, without depending on their cloud. | `infra-providers` | Cross | P2 | M | `DEFERRED` | +| [`GT-537`](./gap-reference-catalog.md#gt-537) | **[Scorecards pack] GEO / AI-discoverability dimension (Claude SEO pattern).** Optional Scorecards pack inspired by the Claude SEO multi-agent audit (score + severity plan); validates that the multi-agent→scorecard pattern scales. Not a Core capability — a product pack in the Portal/Scorecards plane. | `Tracker` | Cross | P3 | L | `DEFERRED` | | [`GT-486`](./gap-reference-catalog.md#gt-486) | **cli did not emit a parseable ADR-0073 envelope for sdlc-status.** Output could not be parsed into an { success, data\|error, meta } envelope. (Auto-detected by the exploratory test agent on operation `sdlc-status`.) | `Evolith CLI` | Cross | P2 | S | `DONE` | | [`GT-487`](./gap-reference-catalog.md#gt-487) | **cli did not emit a parseable ADR-0073 envelope for sdlc-handoff.** Output could not be parsed into an { success, data\|error, meta } envelope. (Auto-detected by the exploratory test agent on operation `sdlc-handoff`.) | `Evolith CLI` | Cross | P2 | S | `DONE` | | [`GT-490`](./gap-reference-catalog.md#gt-490) | **cli did not emit a parseable ADR-0073 envelope for sdlc-generate.** Output could not be parsed into an { success, data\|error, meta } envelope. (Auto-detected by the exploratory test agent on operation `sdlc-generate`.) | `Evolith CLI` | Cross | P2 | S | `DONE` | From 570667321d418cabe15a9cc0ffcd0af533f3e4a9 Mon Sep 17 00:00:00 2001 From: aarroyo Date: Mon, 13 Jul 2026 11:09:25 -0500 Subject: [PATCH 2/3] =?UTF-8?q?docs(gaps):=20GT-447=20=E2=80=94=20full=20T?= =?UTF-8?q?racker=E2=86=92Core=E2=86=92Postgres=20chain=20verified=20on=20?= =?UTF-8?q?local=20kind?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Deployed the Tracker (Postgres + BFF + web) into the kind cluster wired to the real Core; POST /api/core/evaluate drove a real core-api /api/v1/evaluate (200 ALLOW from the tracker pod) and persisted a completed CoreEvaluationTransaction. Objetivo 1 governance chain functional end-to-end on kind; only the browser UI check remains. Co-Authored-By: Claude Opus 4.8 --- reference/core/control-center/gaps/gap-tracking.es.md | 2 +- reference/core/control-center/gaps/gap-tracking.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/core/control-center/gaps/gap-tracking.es.md b/reference/core/control-center/gaps/gap-tracking.es.md index 77c1d86bf..6cb6ff37c 100644 --- a/reference/core/control-center/gaps/gap-tracking.es.md +++ b/reference/core/control-center/gaps/gap-tracking.es.md @@ -100,7 +100,7 @@ Este tablero es la única fuente de verdad para deuda técnica, gaps, oportunida | [`GT-460`](./gap-reference-catalog.es.md#gt-460) | **Los conteos de la superficie MCP del comando `api` están hardcodeados y se desincronizan del server real.** `api -l` reporta "23 tools / 8 resources", pero un smoke stdio del `@beyondnet/evolith-mcp` en ejecución devuelve **35 tools / 9 resources** (`tools/list`/`resources/list`). La fuente `api.catalog.ts` hardcodea los conteos como strings de descripción. Fix: derivar los conteos/catálogo del registry vivo de tools+resources del MCP (o regenerarlos en CI, cf. GT-445). **EN-PROGRESO (rama): añadido `scripts/gen-api-catalog.mjs` (introspecciona el MCP server vivo) → `api.catalog.generated.ts` commiteado; `api --list` ahora muestra los 35 tools / 9 resources reales con conteos derivados de los arrays, y el footer obsoleto `evolith mcp serve` → `evolith-mcp serve`. Follow-on: enumeración completa de SCHEMAS/COMMANDS + guard de CI que regenere y compare.** | `Evolith CLI` | Cross | P2 | S | `COMPLETADO` | | [`GT-465`](./gap-reference-catalog.es.md#gt-465) | ✅ **Hecho:** `kind-cluster.yaml` con `disableDefaultCNI:true` (kindnet off → Cilium aplica la política; el README añade el paso de instalación de Cilium); `deploy/kubernetes/network-policies.yaml` (22 políticas) codifica el modelo §7 — default-deny por ns de producto + allows DNS/broker/Core/OTLP/ingress/intra-ns, con el invariante estructural de que `evolith-core` NO tiene ruta al :5672. **kindnet no aplica NetworkPolicy → el modelo default-deny quedaba sin efecto.** Follow-on: aserciones allow/deny en G1. Riesgo §15 #13 (🟡). | `Infra` | Release | P2 | M | `COMPLETADO` | | [`GT-464`](./gap-reference-catalog.es.md#gt-464) | **Broker RabbitMQ = dependencia crítica compartida.** §5.6/§15: mitigado — el outbox transaccional de MMS (validado en vivo) hace las caídas del broker sin pérdida (el productor commitea, los consumidores se ponen al día al reconectar); la readiness nunca depende del broker (§5.4), así que una caída degrada solo frescura, nunca correctitud. Acción permanente: monitoreo + broker con quorum de ≥3 nodos + alertas bus-disconnected/lag. Riesgo §15 #10 (🟠, mitigado → DIFERIDO). | `Infra` | Cross | P2 | S | `DIFERIDO` | -| [`GT-447`](./gap-reference-catalog.es.md#gt-447) | **MILESTONE — Objetivo 1: stack completo FUNCIONAL EN LOCAL (Docker/Kubernetes).** Levantar el chain completo — Tracker BFF/API → Evolith Core (CLI, core-api, MCP, agent-runtime) — con adapters REALES (no stubs), integración real Tracker↔Core `evaluate()`, y la UI (tracker-web) conectada a las URLs LOCALES. El refactor de diseño de la UI se difiere a Fase 2. Bring-up de un comando (docker-compose / kind). Reúne el subset M1 de GT-435: GT-438 (adapters reales), GT-446 (integración Tracker + DB local), GT-436 (publicar paquetes 1.0.0 reales en npm — cuando estén genuinamente listos), GT-439 (auth fail-closed + tenant guard), GT-440 (observabilidad), compose/k8s local. Solo HITL real / pen-test relajados para local. **EN-PROGRESO (`9f4d592b`):** el **stack Core levantó FUNCIONAL en kind** — `local-test.sh kind-apps-up` (rutas repunteadas post-refactor) buildea las 3 imágenes, crea el cluster `evolith`, carga imágenes, instala los 3 charts Helm; los **3 pods `1/1 Running`**, rollouts verdes. Smoke verificado: `/health` de core-api (envelope ADR-0073), mcp y agent-runtime OK, y **`POST /v1/agent/handle` ejecutó la cadena gobernada completa** (resolve-context→select-capability→policy-preflight→harness-execute→core-evaluate→policy-validate→completed, `verdict: PASS`, `policyEngine: opa`). **Pendiente:** el chain del Tracker BFF/API→Core (cross-repo, GT-446) + la UI en navegador. | `Cross` | Cross | P0 | L | `EN-PROGRESO` | +| [`GT-447`](./gap-reference-catalog.es.md#gt-447) | **MILESTONE — Objetivo 1: stack completo FUNCIONAL EN LOCAL (Docker/Kubernetes).** Levantar el chain completo — Tracker BFF/API → Evolith Core (CLI, core-api, MCP, agent-runtime) — con adapters REALES (no stubs), integración real Tracker↔Core `evaluate()`, y la UI (tracker-web) conectada a las URLs LOCALES. El refactor de diseño de la UI se difiere a Fase 2. Bring-up de un comando (docker-compose / kind). Reúne el subset M1 de GT-435: GT-438 (adapters reales), GT-446 (integración Tracker + DB local), GT-436 (publicar paquetes 1.0.0 reales en npm — cuando estén genuinamente listos), GT-439 (auth fail-closed + tenant guard), GT-440 (observabilidad), compose/k8s local. Solo HITL real / pen-test relajados para local. **EN-PROGRESO (`9f4d592b`):** el **stack Core levantó FUNCIONAL en kind** — `local-test.sh kind-apps-up` (rutas repunteadas post-refactor) buildea las 3 imágenes, crea el cluster `evolith`, carga imágenes, instala los 3 charts Helm; los **3 pods `1/1 Running`**, rollouts verdes. Smoke verificado: `/health` de core-api (envelope ADR-0073), mcp y agent-runtime OK, y **`POST /v1/agent/handle` ejecutó la cadena gobernada completa** (resolve-context→select-capability→policy-preflight→harness-execute→core-evaluate→policy-validate→completed, `verdict: PASS`, `policyEngine: opa`). **Pendiente:** el chain del Tracker BFF/API→Core (cross-repo, GT-446) + la UI en navegador. **+chain COMPLETO verificado en kind (2026-07-13):** desplegado el Tracker (Postgres + tracker-api BFF + tracker-web) en el MISMO cluster kind, cableado al Core REAL de `evolith-local` (FQDN cross-namespace + API key). `POST /api/core/evaluate` → `POST core-api /api/v1/evaluate` real (SecurityAudit `200 ALLOW 104ms`, desde el pod del Tracker) → transacción persistida (`status=completed`) en `tracker_governance.core_evaluation_transactions`. Fixes (repo evolith_tracker, branch `fix/local-kind-core-wiring`): values-local→Core real, y `ConnectionStrings__MasterDataDb` (el `TenantProjectionMigrator` crasheaba en localhost). **Resta solo:** verificar la UI React en navegador. | `Cross` | Cross | P0 | L | `EN-PROGRESO` | | [`GT-448`](./gap-reference-catalog.es.md#gt-448) | **MILESTONE — Objetivo 2: PRODUCCIÓN en la VPS (Coolify + Kubernetes), UI incluida** — tras completar el Objetivo 1 (GT-447) y validarlo. Reúne el subset M2 de GT-435 — los ítems del paso a la VPS: GT-324 (CD deploy), GT-437 (CI/CD del agent-runtime), GT-441 (HITL real), GT-442 (secrets/DB prod), GT-443 (reliability), GT-444 (pen-test), GT-445 (reconciliación de docs) + el refactor de diseño de UI de Fase 2. (GT-436 publicación npm 1.0.0, GT-439 auth fail-closed y GT-440 observabilidad movidos al Objetivo 1.) | `Cross` | Cross | P1 | XL | `PENDIENTE` | | [`GT-435`](./gap-reference-catalog.es.md#gt-435) | EPIC — Camino a Producción del diagrama conceptual de la suite (Core hubs → Hermes/Agent Runtime → Exposición CLI/API/MCP → Tracker → satélites). Evaluación 2026-07-04: Core ~95% listo (L4); el único bloqueante de CD activo es `GT-324`; la distribución está bloqueada por la deprecación a 0.0.1; el agent-runtime usa stubs por defecto; el Tracker es un scaffold .NET real pero desfasado del diseño actual de Core. **Umbrella — descompuesto en `GT-436`…`GT-446` (+ `GT-324`), organizado en dos milestones: `GT-447` (Objetivo 1 — funcional local) y `GT-448` (Objetivo 2 — producción).** | `Cross` | Cross | P0 | XL | `PENDIENTE` | | [`GT-436`](./gap-reference-catalog.es.md#gt-436) | Publicar los paquetes npm. El scope viejo `@evolith/*` estaba contaminado con historial publicado (1.0.x/1.1.x/2.0.0-beta/tombstones) que bloqueaba un 1.0.0 limpio, así que se renombró toda la familia a un scope nuevo unificado. **HECHO (0edaa22b): los 7 libs publicados a `1.0.0` limpio bajo `@beyondnet/evolith-*` (core-domain, infra-providers, core, agent-runtime, sdk, mcp, cli — todos HTTP 200 en el registry). Viejos `@evolith/*` deprecados apuntando a los nuevos (4 quedaron en estado 404 corrupto del registry, inservibles de todos modos).** Follow-on: barrido de docs `@evolith/*` → `@beyondnet/evolith-*`. | `CLI` | Cross | P0 | M | `COMPLETADO` | diff --git a/reference/core/control-center/gaps/gap-tracking.md b/reference/core/control-center/gaps/gap-tracking.md index 5e292cf1e..953198020 100644 --- a/reference/core/control-center/gaps/gap-tracking.md +++ b/reference/core/control-center/gaps/gap-tracking.md @@ -100,7 +100,7 @@ This board is the single source of truth for technical debt, gaps, opportunities | [`GT-460`](./gap-reference-catalog.md#gt-460) | **`api` command's MCP-surface counts are hardcoded and drift from the live server.** `api -l` reports "23 tools / 8 resources", but a stdio smoke of the running `@beyondnet/evolith-mcp` server returns **35 tools / 9 resources** (`tools/list`/`resources/list`). Source `api.catalog.ts` hardcodes the counts as description strings. Fix: derive the counts/catalog from the live MCP tool+resource registry (or regenerate them in CI, cf. GT-445). **IN-PROGRESS (branch): added `scripts/gen-api-catalog.mjs` (introspects the live MCP server) → checked-in `api.catalog.generated.ts`; `api --list` now shows the real 35 tools / 9 resources with counts derived from the arrays, and the stale `evolith mcp serve` footer → `evolith-mcp serve`. Follow-on: full SCHEMAS/COMMANDS enumeration + a CI guard that regenerates and diffs.** | `Evolith CLI` | Cross | P2 | S | `DONE` | | [`GT-465`](./gap-reference-catalog.md#gt-465) | ✅ **Done:** `kind-cluster.yaml` sets `disableDefaultCNI:true` (kindnet off → Cilium enforces policy; README adds the Cilium install step); `deploy/kubernetes/network-policies.yaml` (22 policies) codifies the §7 model — default-deny per product ns + DNS/broker/Core/OTLP/ingress/intra-ns allows, with the structural invariant that `evolith-core` has NO path to :5672. **kindnet doesn't enforce NetworkPolicy → the default-deny model was silently ineffective.** Follow-on: allow/deny assertions in G1. Risk §15 #13 (🟡). | `Infra` | Release | P2 | M | `DONE` | | [`GT-464`](./gap-reference-catalog.md#gt-464) | **RabbitMQ broker = shared critical dependency.** §5.6/§15: mitigated — MMS's transactional outbox (validated live) makes broker outages lossless (the producer commits, consumers catch up on reconnect); readiness never gates on the broker (§5.4), so an outage degrades freshness only, never correctness. Standing action: monitoring + a quorum broker with ≥3 nodes + bus-disconnected/lag alerts. Risk §15 #10 (🟠, mitigated → DEFERRED). | `Infra` | Cross | P2 | S | `DEFERRED` | -| [`GT-447`](./gap-reference-catalog.md#gt-447) | **MILESTONE — Objective 1: full stack FUNCTIONAL LOCALLY (Docker/Kubernetes).** Bring up the whole chain — Tracker BFF/API → Evolith Core (CLI, core-api, MCP, agent-runtime) — with REAL adapters (not stubs), real Tracker↔Core `evaluate()` integration, and the UI (tracker-web) connected to the LOCAL URLs. UI design refactor is deferred to Phase 2. One-command bring-up (docker-compose / kind). Gathers the M1 subset of GT-435: GT-438 (real adapters), GT-446 (Tracker integration + local DB), GT-436 (publish real 1.0.0 packages to npm — when genuinely ready), GT-439 (fail-closed auth + tenant guard), GT-440 (observability), local compose/k8s. Only real HITL / pen-test relaxed for local. **IN-PROGRESS (`9f4d592b`):** the **Core stack came up FUNCTIONAL on kind** — `local-test.sh kind-apps-up` (paths repointed post-refactor) builds the 3 images, creates the `evolith` cluster, loads images, installs the 3 Helm charts; **all 3 pods `1/1 Running`**, rollouts green. Smoke verified: core-api `/health` (ADR-0073 envelope), mcp and agent-runtime OK, and **`POST /v1/agent/handle` ran the full governed chain** (resolve-context→select-capability→policy-preflight→harness-execute→core-evaluate→policy-validate→completed, `verdict: PASS`, `policyEngine: opa`). **Remaining:** the Tracker BFF/API→Core chain (cross-repo, GT-446) + the browser UI. | `Cross` | Cross | P0 | L | `IN-PROGRESS` | +| [`GT-447`](./gap-reference-catalog.md#gt-447) | **MILESTONE — Objective 1: full stack FUNCTIONAL LOCALLY (Docker/Kubernetes).** Bring up the whole chain — Tracker BFF/API → Evolith Core (CLI, core-api, MCP, agent-runtime) — with REAL adapters (not stubs), real Tracker↔Core `evaluate()` integration, and the UI (tracker-web) connected to the LOCAL URLs. UI design refactor is deferred to Phase 2. One-command bring-up (docker-compose / kind). Gathers the M1 subset of GT-435: GT-438 (real adapters), GT-446 (Tracker integration + local DB), GT-436 (publish real 1.0.0 packages to npm — when genuinely ready), GT-439 (fail-closed auth + tenant guard), GT-440 (observability), local compose/k8s. Only real HITL / pen-test relaxed for local. **IN-PROGRESS (`9f4d592b`):** the **Core stack came up FUNCTIONAL on kind** — `local-test.sh kind-apps-up` (paths repointed post-refactor) builds the 3 images, creates the `evolith` cluster, loads images, installs the 3 Helm charts; **all 3 pods `1/1 Running`**, rollouts green. Smoke verified: core-api `/health` (ADR-0073 envelope), mcp and agent-runtime OK, and **`POST /v1/agent/handle` ran the full governed chain** (resolve-context→select-capability→policy-preflight→harness-execute→core-evaluate→policy-validate→completed, `verdict: PASS`, `policyEngine: opa`). **Remaining:** the Tracker BFF/API→Core chain (cross-repo, GT-446) + the browser UI. **+full chain verified on kind (2026-07-13):** deployed the Tracker (Postgres + tracker-api BFF + tracker-web) into the SAME kind cluster, wired to the REAL Core in `evolith-local` (cross-namespace FQDN + API key). `POST /api/core/evaluate` → real `POST core-api /api/v1/evaluate` (SecurityAudit `200 ALLOW 104ms`, from the tracker pod) → transaction persisted (`status=completed`) in `tracker_governance.core_evaluation_transactions`. Fixes (evolith_tracker repo, branch `fix/local-kind-core-wiring`): values-local→real Core, and `ConnectionStrings__MasterDataDb` (the `TenantProjectionMigrator` was crashlooping on localhost). **Only remaining:** verify the React UI in a browser. | `Cross` | Cross | P0 | L | `IN-PROGRESS` | | [`GT-448`](./gap-reference-catalog.md#gt-448) | **MILESTONE — Objective 2: PRODUCTION on the VPS (Coolify + Kubernetes), UI included** — after Objective 1 (GT-447) is done and validated. Gathers the M2 subset of GT-435 — the VPS-pass items: GT-324 (CD deploy), GT-437 (agent-runtime CI/CD), GT-441 (real HITL), GT-442 (secrets/DB prod), GT-443 (reliability), GT-444 (pen-test), GT-445 (doc reconcile) + the Phase-2 UI design refactor. (GT-436 npm 1.0.0 publish, GT-439 fail-closed auth and GT-440 observability moved to Objective 1.) | `Cross` | Cross | P1 | XL | `PENDING` | | [`GT-435`](./gap-reference-catalog.md#gt-435) | EPIC — Road to Production of the conceptual suite diagram (Core hubs → Hermes/Agent Runtime → Exposure CLI/API/MCP → Tracker → satellites). Assessment 2026-07-04: Core ~95% ready (L4); the sole active CD blocker is `GT-324`; distribution blocked by the 0.0.1 package deprecation; agent-runtime defaults to stubs; Tracker is a real .NET scaffold but lagging the current Core design. **Umbrella — decomposed into `GT-436`…`GT-446` (+ `GT-324`), organized under two milestones: `GT-447` (Objective 1 — local functional) and `GT-448` (Objective 2 — production).** | `Cross` | Cross | P0 | XL | `PENDING` | | [`GT-436`](./gap-reference-catalog.md#gt-436) | Ship the npm packages. The old `@evolith/*` scope was polluted with published history (1.0.x/1.1.x/2.0.0-beta/tombstones) that blocked a clean 1.0.0, so the whole library family was renamed to a fresh unified scope. **DONE (0edaa22b): all 7 libs published at a clean `1.0.0` under `@beyondnet/evolith-*` (core-domain, infra-providers, core, agent-runtime, sdk, mcp, cli — all HTTP 200 on the registry). Old `@evolith/*` deprecated pointing to the new names (4 are in a broken 404 registry state and unusable anyway).** Follow-on: sweep the docs from `@evolith/*` → `@beyondnet/evolith-*`. | `CLI` | Cross | P0 | M | `DONE` | From 6254a6b4b92f2e294cbc40cd88b59c7da82a7eef Mon Sep 17 00:00:00 2001 From: aarroyo Date: Mon, 13 Jul 2026 11:10:34 -0500 Subject: [PATCH 3/3] =?UTF-8?q?docs(gaps):=20bump=20progress=20counters=20?= =?UTF-8?q?for=20GT-533=E2=80=A6537=20(537=20total=20=C2=B7=2012=20pending?= =?UTF-8?q?=20=C2=B7=204=20deferred)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The evidence-adapter wave added 3 PENDING + 2 DEFERRED rows; sync the declared Progress/Progreso counters so 08-validate-tracking reconciles (was 532). Guard green locally: 537 gaps validated. Co-Authored-By: Claude Opus 4.8 --- reference/core/control-center/gaps/gap-tracking.es.md | 2 +- reference/core/control-center/gaps/gap-tracking.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/core/control-center/gaps/gap-tracking.es.md b/reference/core/control-center/gaps/gap-tracking.es.md index 6cb6ff37c..a54fad1ff 100644 --- a/reference/core/control-center/gaps/gap-tracking.es.md +++ b/reference/core/control-center/gaps/gap-tracking.es.md @@ -552,7 +552,7 @@ Este tablero es la única fuente de verdad para deuda técnica, gaps, oportunida | [`GT-246`](./gap-reference-catalog.es.md#gt-246) | Implementar experimentos Chaos Mesh/Litmus | `QA` | Cross | P3 | L | `COMPLETADO` | -**Progreso:** 503 / 532 completados · 18 en progreso · 9 pendientes · 2 diferido +**Progreso:** 503 / 537 completados · 18 en progreso · 12 pendientes · 4 diferidos **Oleada 2026-06-23 (auditoría profunda de Winston III):** Añadidos 14 gaps nuevos `GT-212`…`GT-225` del Winston Audit Playbook que cubren: higiene de estado ADR (GT-212), metadata + presupuestos operativos + corpus de guías por topología (GT-213, GT-217, GT-219), observabilidad + OpenAPI en controladores REST (GT-214, GT-215), paridad de input-schemas OPA + densidad de tests por topología (GT-216, GT-222), plantillas de rollback + on-call de Fase 05 (GT-218), cobertura de ramas CLI + paridad de envelope --format + limpieza de skip-list (GT-220, GT-224, GT-225), audit logging HTTP de MCP (GT-221), y tests e2e de paridad cross-surface (GT-223). diff --git a/reference/core/control-center/gaps/gap-tracking.md b/reference/core/control-center/gaps/gap-tracking.md index 953198020..0f6b072ff 100644 --- a/reference/core/control-center/gaps/gap-tracking.md +++ b/reference/core/control-center/gaps/gap-tracking.md @@ -552,7 +552,7 @@ This board is the single source of truth for technical debt, gaps, opportunities | [`GT-246`](./gap-reference-catalog.md#gt-246) | Implement Chaos Mesh/Litmus experiments | `QA` | Cross | P3 | L | `DONE` | -**Progress:** 503 / 532 done · 18 in progress · 9 pending · 2 deferred +**Progress:** 503 / 537 done · 18 in progress · 12 pending · 4 deferred **Wave 2026-06-23 (Winston deep audit III):** Added 14 new gaps `GT-212`…`GT-225` from the Winston Audit Playbook covering: ADR status hygiene (GT-212), topology manifest metadata + operational budgets + guidance corpus (GT-213, GT-217, GT-219), REST controller observability + OpenAPI (GT-214, GT-215), OPA input-schema parity + per-topology test density (GT-216, GT-222), SDLC Phase 05 rollback + on-call templates (GT-218), CLI branch coverage + envelope format coverage + skip-list cleanup (GT-220, GT-224, GT-225), MCP HTTP audit logging (GT-221), and cross-surface parity e2e tests (GT-223).