From 17adc223c1805e15ec78a079c241c3f3fd6a4666 Mon Sep 17 00:00:00 2001 From: aarroyo Date: Sat, 1 Aug 2026 22:40:21 -0500 Subject: [PATCH] =?UTF-8?q?docs(i18n):=20translate=20C4=20topology=20and?= =?UTF-8?q?=20Discovery=20Canvas=20=E2=80=94=20close=20GAP-011,=20GAP-017?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both rows were TRUE, and both had been marked DONE on the other board while the defect was still there. c4-macro-topology-phase1.md carried the banner English (this document) and 86 of its 87 non-empty lines were byte-identical to the Spanish file: only the navigation banner had been translated. DISCOVERY_CANVAS.md was 23 of 24. Both passed check-bilingual-parity, which compares that the pair exists and that the headers match, and can see neither language nor content. Both are now genuinely English — prose, mermaid node descriptions and relationship labels — and their entries are removed from untranslated-allowlist.json, which drops from 9 declared to 7. That file is a list of promises, so shrinking it is the point. Verified after translating that no line still identical to the Spanish file contains Spanish prose: the remaining overlap is fences, braces and identifiers. --- .../tracker-gaps-opportunities-tracking.md | 18 +-- docs/audit/untranslated-allowlist.json | 8 -- .../architecture/c4-macro-topology-phase1.md | 120 +++++++++--------- reference/specs/discovery/DISCOVERY_CANVAS.md | 56 ++++---- 4 files changed, 97 insertions(+), 105 deletions(-) diff --git a/docs/audit/tracker-gaps-opportunities-tracking.md b/docs/audit/tracker-gaps-opportunities-tracking.md index 0fa75929..58e3e50d 100644 --- a/docs/audit/tracker-gaps-opportunities-tracking.md +++ b/docs/audit/tracker-gaps-opportunities-tracking.md @@ -25,13 +25,13 @@ This document is the only operational gap register in this repository. The maste | # | Status | ID | Type | Category | Component | Module | Story(ies) | Description | Resolution / Next Step | Criticality | Complexity | |---:|---|---|---|---|---|---|---|---|---|:---:|:---:| -| 1 | 🟡 OPEN | [GAP-011](#detail-gap-011) | Docs | Documentation gap | Docs | Docs | N/A | C4 Topology No English version | CONFIRMED and MEASURED 2026-08-01. The row is right, and the file EXISTS — that is the trap. `X.md` is present, labelled «English (this document)», and written in Spanish, so `check-bilingual-parity` passes it: that guard compares file presence and header counts, neither of which sees language. `check-translation-language` does, and found **9 documents in this state of 143 paired**, including `DECISIONS.md` (128 Spanish markers to 1 English) and `MASTER_INDEX.md`. This row names one of the nine; all nine are declared with a reason in `untranslated-allowlist.json`, so the debt is counted rather than invisible and the tenth fails CI. | 🟡 MEDIUM | 🟡 MEDIUM | -| 2 | 🟡 OPEN | [GAP-016](#detail-gap-016) | Docs | Documentation gap | Docs | Docs | N/A | Roadmap Has No Calendar Dates | Pending owner/action definition in this register. | 🟡 MEDIUM | 🟡 MEDIUM | -| 3 | 🟡 OPEN | [GAP-017](#detail-gap-017) | Docs | Documentation gap | Docs | Docs | N/A | Discovery Canvas Has No ES Version | CONFIRMED and MEASURED 2026-08-01. The row is right, and the file EXISTS — that is the trap. `X.md` is present, labelled «English (this document)», and written in Spanish, so `check-bilingual-parity` passes it: that guard compares file presence and header counts, neither of which sees language. `check-translation-language` does, and found **9 documents in this state of 143 paired**, including `DECISIONS.md` (128 Spanish markers to 1 English) and `MASTER_INDEX.md`. This row names one of the nine; all nine are declared with a reason in `untranslated-allowlist.json`, so the debt is counted rather than invisible and the tenth fails CI. | 🟡 MEDIUM | 🟡 MEDIUM | -| 4 | 🟡 OPEN | [GAP-023](#detail-gap-023) | Docs | Documentation gap | Docs | Docs | N/A | Re-Do Flow Not Fully Designed | Pending owner/action definition in this register. | 🟡 MEDIUM | 🟡 MEDIUM | -| 5 | 🟡 OPEN | [GAP-025](#detail-gap-025) | Docs | Documentation gap | Docs | Docs | N/A | Portal DDD incomplete — NARROWED 2026-08-01: the strategic-map half is DONE (`reference/specs/architecture/bounded-context-map.md` calls itself «the single, authoritative strategic map» of the 9 contexts, with integration patterns and cross-context events). What remains is the four support contexts. | Only the remaining half is open. Withdrawn from `falsifiable-claims.json`: «four support contexts» needs judgement about WHICH four, and a probe that pretended to check it would refute the row on any document mentioning a context. | 🟡 MEDIUM | 🟡 MEDIUM | -| 6 | 🟡 OPEN | [COH-012](#detail-coh-012) | GAP | Missing capability / corrective gap | Backend | Discovery | US-DIS-006 | Gherkin covers only 2 of 4 CRUD operations (Create, Update). Delete and Read entirely missing. Zero edge cases. | Pending owner/action definition in this register. | 🟢 | 🟢 | -| 7 | 🟡⏳ DEFERRED | [OPP-002](#detail-opp-002) | OPP | Improvement opportunity | Backend | N/A | N/A | Extraer AuditTrail como Shared Kernel — 5+ contextos implementan historiales inmutables | Pending owner/action definition in this register. | 🟠 HIGH | 🔴 HIGH | +| 1 | 🟡 OPEN | [GAP-016](#detail-gap-016) | Docs | Documentation gap | Docs | Docs | N/A | Roadmap Has No Calendar Dates | Pending owner/action definition in this register. | 🟡 MEDIUM | 🟡 MEDIUM | +| 2 | 🟡 OPEN | [GAP-023](#detail-gap-023) | Docs | Documentation gap | Docs | Docs | N/A | Re-Do Flow Not Fully Designed | Pending owner/action definition in this register. | 🟡 MEDIUM | 🟡 MEDIUM | +| 3 | 🟡 OPEN | [GAP-025](#detail-gap-025) | Docs | Documentation gap | Docs | Docs | N/A | Portal DDD incomplete — NARROWED 2026-08-01: the strategic-map half is DONE (`reference/specs/architecture/bounded-context-map.md` calls itself «the single, authoritative strategic map» of the 9 contexts, with integration patterns and cross-context events). What remains is the four support contexts. | Only the remaining half is open. Withdrawn from `falsifiable-claims.json`: «four support contexts» needs judgement about WHICH four, and a probe that pretended to check it would refute the row on any document mentioning a context. | 🟡 MEDIUM | 🟡 MEDIUM | +| 4 | 🟡 OPEN | [COH-012](#detail-coh-012) | GAP | Missing capability / corrective gap | Backend | Discovery | US-DIS-006 | Gherkin covers only 2 of 4 CRUD operations (Create, Update). Delete and Read entirely missing. Zero edge cases. | Pending owner/action definition in this register. | 🟢 | 🟢 | +| 5 | 🟡⏳ DEFERRED | [OPP-002](#detail-opp-002) | OPP | Improvement opportunity | Backend | N/A | N/A | Extraer AuditTrail como Shared Kernel — 5+ contextos implementan historiales inmutables | Pending owner/action definition in this register. | 🟠 HIGH | 🔴 HIGH | +| 6 | 🟢 RESOLVED | [GAP-011](#detail-gap-011) | Docs | Documentation gap | Docs | Docs | N/A | C4 Topology No English version | RESOLVED — the row was TRUE and had been mismeasured. `c4-macro-topology-phase1.md` existed, was labelled «English (this document)» and passed `check-bilingual-parity`, but 86 of its 87 non-empty lines were byte-identical to the Spanish file: only the navigation banner had been translated. It is now genuinely in English — prose, diagram descriptions and relationship labels — and its entry was removed from `untranslated-allowlist.json`, which drops from 9 declared to 7. Note for the record: the other board, `tracker-gap-tracking.md`, marked this DONE while the file was still Spanish. | 🟡 MEDIUM | 🟡 MEDIUM | +| 7 | 🟢 RESOLVED | [GAP-017](#detail-gap-017) | Docs | Documentation gap | Docs | Docs | N/A | Discovery Canvas Has No ES Version | RESOLVED — same defect and same correction as GAP-011. `DISCOVERY_CANVAS.md` was 23 of 24 non-empty lines identical to `DISCOVERY_CANVAS.es.md`; the English label was the only English in it. Now translated in full and removed from `untranslated-allowlist.json`. Both boards had this backwards on direction — one said the ES version was missing, the other said the EN one was — and what was actually missing was English content behind an English filename. | 🟡 MEDIUM | 🟡 MEDIUM | | 8 | 🟢 RESOLVED | [COH-009](#detail-coh-009) | INCO | Source incoherence | Backend | Release | All REL | BR-003 conflated: product-brief = "no deploy without QA gate", but 5+ stories invoke as "human authorization required." Two rules sharing one ID. | RESOLVED — and the repository says so in the row's own words. The business-rule table in `evolith-tracker-crosscutting-diagram.md` now carries a `BR-010` row, *CFR Quality Threshold*, whose own description reads «escindida de BR-003 por COH-009; BR-003 es sólo la firma humana». The split this row asked for was made, credited to this row, and the row was never moved. Verified across the repository: every `BR-003` occurrence outside the audit tree means Human Sign-Off and nothing else, and the QA-gate half lives as `BR-010` — cited by `reference/specs/qa/` («no deployment is authorized without an approved QA verdict and CFR < 2%»), by the test strategy against `PhaseGateEvaluator`, and by the Re-Do flow design. Two rules, two ids. | 🟢 | 🟢 | | 9 | 🟢 RESOLVED | [GAP-013](#detail-gap-013) | Docs | Documentation gap | Docs | Docs | N/A | 14 Technical Design Docs Lack ES Version | REFUTED and MEASURED 2026-08-01. The row says 14 technical design documents lack a Spanish version. `reference/specs/design/` holds **20** documents and **every one** has its `.es.md` — zero missing. Repository-wide, 19 `.md` files have no Spanish pair, and **9 of them are under `docs/audit/`**: audit reports, corpus triages and this register itself, which are working documents rather than product documentation. The other ten are READMEs and task notes (`robosoft/README.md`, `product/infra/helm/README.md`, `Tracker.ArchitectureTests/README.md`, `docs/tasks/*`). None is a technical design document. **A related defect DOES survive and is tracked elsewhere:** having the pair is not having the translation — `check-translation-language` found 9 documents whose `.md` is written in Spanish, which is what `GAP-011` and `GAP-017` are about. | 🟡 MEDIUM | 🟡 MEDIUM | | 10 | 🟢 RESOLVED | [GAP-015](#detail-gap-015) | Docs | Documentation gap | Docs | Docs | N/A | DECISIONS.md Lacks Description of T-001 Technical Rationale | Resolved 2026-08-01 by writing `docs/adrs/T-001-nx-monorepo-orchestration.md` (+ `.es`). **The row was right and understated it:** the single line T-001 did carry was also WRONG. It said «npm workspaces con Nx», and no `package.json` in this repository declares a `workspaces` field — Nx orchestrates by PROJECT GRAPH (`project.json` plus the `@nx/vite`, `@nx/webpack`, `@nx/eslint` and `@nx/jest` inference plugins in `src/nx.json`). A reader would have looked for a `workspaces` array, not found one, and concluded the monorepo was misconfigured. The ADR records the reason that decided it — `tracker-api` is .NET, and npm workspaces links `node_modules` between npm packages, so it would have covered three projects of four and left the largest outside — and the DECISIONS entry is corrected in both languages. | 🟡 MEDIUM | 🟡 MEDIUM | @@ -332,7 +332,7 @@ This document is the only operational gap register in this repository. The maste ### Detail GAP-011 -- **Status:** 🟡 OPEN +- **Status:** 🟢 RESOLVED - **Type:** Docs (Documentation gap) - **Component:** Docs - **Module:** Docs @@ -396,7 +396,7 @@ This document is the only operational gap register in this repository. The maste ### Detail GAP-017 -- **Status:** 🟡 OPEN +- **Status:** 🟢 RESOLVED - **Type:** Docs (Documentation gap) - **Component:** Docs - **Module:** Docs diff --git a/docs/audit/untranslated-allowlist.json b/docs/audit/untranslated-allowlist.json index 16b77586..3bbc3bcb 100644 --- a/docs/audit/untranslated-allowlist.json +++ b/docs/audit/untranslated-allowlist.json @@ -17,14 +17,6 @@ "file": "docs/adrs/T-044-single-tenant-isolation-model.md", "reason": "ADR awaiting PO ratification (its own Status says so). Translating an unratified decision would produce two versions to keep in step while its content may still change." }, - { - "file": "reference/specs/discovery/DISCOVERY_CANVAS.md", - "reason": "This IS `GAP-017` — the row is correct and stays open. Listed so the guard measures it instead of asserting it." - }, - { - "file": "reference/specs/architecture/c4-macro-topology-phase1.md", - "reason": "This IS `GAP-011` — the row is correct and stays open. Listed so the guard measures it instead of asserting it." - }, { "file": "reference/specs/architecture/scale-out-strategy.md", "reason": "Tracked by GAP-013." diff --git a/reference/specs/architecture/c4-macro-topology-phase1.md b/reference/specs/architecture/c4-macro-topology-phase1.md index 6bfdf481..ca80530f 100644 --- a/reference/specs/architecture/c4-macro-topology-phase1.md +++ b/reference/specs/architecture/c4-macro-topology-phase1.md @@ -1,123 +1,123 @@ -# C4 Model: Evolith Tracker (Fase 1 - MVP Topology) +# C4 Model: Evolith Tracker (Phase 1 - MVP Topology) > **Bilingual Navigation:** English (this document) · [Versión en Español](./c4-macro-topology-phase1.es.md) -Este documento detalla la arquitectura a nivel de Contexto y Contenedores para la Fase 1 del producto, alineada con la **Visión de Governed Composition**. Evolith Tracker actúa como el **Governance Control Plane** que orquesta y audita, mientras delega la ejecución técnica a proveedores externos mediante puertos y adaptadores (ACLs). +This document details the Context- and Container-level architecture for Phase 1 of the product, aligned with the **Governed Composition vision**. Evolith Tracker acts as the **Governance Control Plane** that orchestrates and audits, while delegating technical execution to external providers through ports and adapters (ACLs). -**Condición crítica:** El Backend opera como un Monolito de Despliegue Único con separación por esquemas en Base de Datos (convención `tracker_`, ver [T-008](../../../DECISIONS.md)). El Frontend opera como una arquitectura de **Microfrontends** (Module Federation). +**Critical condition:** The backend runs as a Single-Deployment Monolith with schema-level separation in the database (convention `tracker_`, see [T-008](../../../DECISIONS.md)). The frontend runs as a **Microfrontend** architecture (Module Federation). > [!NOTE] -> **Superficie API (Fase 1):** REST + OpenAPI 3.0 es el único estándar de API expuesto. GraphQL queda fuera de alcance en Fase 1 (ver [T-009](../../../DECISIONS.md)). +> **API surface (Phase 1):** REST + OpenAPI 3.0 is the only API standard exposed. GraphQL is out of scope for Phase 1 (see [T-009](../../../DECISIONS.md)). -## Nivel 1: Diagrama de Contexto del Sistema +## Level 1: System Context Diagram -Muestra el panorama general del Evolith Tracker actuando como el plano de control que centraliza decisiones y delega la ejecución a herramientas de mercado. +Shows the overall landscape, with Evolith Tracker acting as the control plane that centralises decisions and delegates execution to market tooling. ```mermaid C4Context title System Context diagram for Evolith Tracker Suite - Person(human_user, "Human Actor", "Gobernanza humana, autorizaciones y excepciones.") - Person(ai_agent, "Autonomous Agents", "Agentes ejecutando tareas acotadas vía MCP/API.") + Person(human_user, "Human Actor", "Human governance, authorisations and exceptions.") + Person(ai_agent, "Autonomous Agents", "Agents executing scoped tasks via MCP/API.") - System(evolith_tracker, "Evolith Tracker", "Governance Control Plane. Centraliza el estado del SDLC, evalúa Gates y mantiene el Grafo de Evidencias.") + System(evolith_tracker, "Evolith Tracker", "Governance Control Plane. Centralises SDLC state, evaluates Gates and maintains the Evidence Graph.") - System_Ext(core, "Evolith Core", "La Constitución. Provee Reglas, Esquemas y ADRs inmutables.") - System_Ext(ums, "UMS (User Management System)", "Identidad corporativa (AuthN/AuthZ).") + System_Ext(core, "Evolith Core", "The Constitution. Provides immutable Rules, Schemas and ADRs.") + System_Ext(ums, "UMS (User Management System)", "Corporate identity (AuthN/AuthZ).") - System_Ext(work_providers, "Work Systems (Jira, etc.)", "Sistemas operativos de tickets y tareas.") - System_Ext(scm_providers, "SCM & CI/CD (GitHub, .harness)", "Repositorios, pipelines y despliegues.") - System_Ext(obs_providers, "Observability & Analytics", "Langfuse, Superset. Trazas, costos y visualización.") + System_Ext(work_providers, "Work Systems (Jira, etc.)", "Operational ticket and task systems.") + System_Ext(scm_providers, "SCM & CI/CD (GitHub, .harness)", "Repositories, pipelines and deployments.") + System_Ext(obs_providers, "Observability & Analytics", "Langfuse, Superset. Traces, cost and visualisation.") - Rel(human_user, evolith_tracker, "Gobierna, aprueba y audita") - Rel(ai_agent, evolith_tracker, "Consume contexto y provee evidencia") + Rel(human_user, evolith_tracker, "Governs, approves and audits") + Rel(ai_agent, evolith_tracker, "Consumes context and supplies evidence") - Rel(core, evolith_tracker, "Provee reglas de negocio") - Rel(evolith_tracker, ums, "Delega AuthN y Roles") + Rel(core, evolith_tracker, "Provides business rules") + Rel(evolith_tracker, ums, "Delegates AuthN and Roles") - Rel(evolith_tracker, work_providers, "Mapea tickets a evidencias (Port & ACL)") - Rel(evolith_tracker, scm_providers, "Recibe resultados de CI/CD (Port & ACL)") - Rel(evolith_tracker, obs_providers, "Consume telemetría (Port & ACL)") + Rel(evolith_tracker, work_providers, "Maps tickets to evidence (Port & ACL)") + Rel(evolith_tracker, scm_providers, "Receives CI/CD results (Port & ACL)") + Rel(evolith_tracker, obs_providers, "Consumes telemetry (Port & ACL)") ``` -## Nivel 2: Diagrama de Contenedores (Fase 1 Topology) +## Level 2: Container Diagram (Phase 1 Topology) -Muestra la vista interna de la arquitectura en su **Fase 1**. Aquí se refleja la separación entre la API, el motor de decisiones (Gate Decision Engine), y los puertos (Provider Registry). +Shows the internal view of the architecture in its **Phase 1** form. It reflects the separation between the API, the decision engine (Gate Decision Engine), and the ports (Provider Registry). ```mermaid C4Container - title Container diagram for Evolith Tracker (Fase 1) + title Container diagram for Evolith Tracker (Phase 1) System_Ext(ums, "UMS SaaS", "AuthN/AuthZ") - Person(user, "User/Agent", "Interactúa con la Suite") + Person(user, "User/Agent", "Interacts with the Suite") System_Boundary(c1, "Evolith Tracker - Frontend Tier (Microfrontends)") { - Container(shell_host, "Shell Host", "React/Vite", "Orquesta la carga de remotes y layout") + Container(shell_host, "Shell Host", "React/Vite", "Orchestrates remote loading and layout") Container(mfe_gates, "SDLC Gates MFEs", "React Remote", "Discovery, Design, Construction, QA, Release") - Container(mfe_governance, "Governance & Metrics MFE", "React Remote", "Dashboards y auditoría") + Container(mfe_governance, "Governance & Metrics MFE", "React Remote", "Dashboards and audit") } System_Boundary(c2, "Evolith Tracker - Edge Tier") { - Container(api_gateway, "Governance API / BFF", "REST/OpenAPI", "Enruta tráfico y actúa como límite de autorización") + Container(api_gateway, "Governance API / BFF", "REST/OpenAPI", "Routes traffic and acts as the authorisation boundary") } System_Boundary(c3, "Evolith Tracker - Backend Tier (Control Plane)") { - Container(process_orch, "Process & Phase Orchestrator", "Service", "Gestiona el ciclo de vida de los procesos SDLC") - Container(gate_engine, "Gate Decision Engine", "Service", "Toma la decisión canónica evaluando evidencias, reglas y aprobaciones") - Container(evidence_graph, "Evidence Graph Service", "Service", "Mantiene la trazabilidad inmutable y el linaje de datos") - Container(provider_acl, "Provider & Adapter ACL", "Service", "Puertos neutrales (Work, SCM, Observability, Analytics) protegiendo el dominio") + Container(process_orch, "Process & Phase Orchestrator", "Service", "Manages the lifecycle of SDLC processes") + Container(gate_engine, "Gate Decision Engine", "Service", "Makes the canonical decision by evaluating evidence, rules and approvals") + Container(evidence_graph, "Evidence Graph Service", "Service", "Maintains immutable traceability and data lineage") + Container(provider_acl, "Provider & Adapter ACL", "Service", "Neutral ports (Work, SCM, Observability, Analytics) shielding the domain") } System_Boundary(c4, "Evolith Tracker - Data Tier") { - ContainerDb(single_db, "Relational Database", "PostgreSQL", "Schemas segregados lógicamente (tracker_discovery, tracker_release, etc.)") + ContainerDb(single_db, "Relational Database", "PostgreSQL", "Logically segregated schemas (tracker_discovery, tracker_release, etc.)") } - Rel(user, shell_host, "Visita", "HTTPS") - Rel(shell_host, mfe_gates, "Carga", "Module Federation") - Rel(shell_host, mfe_governance, "Carga", "Module Federation") + Rel(user, shell_host, "Visits", "HTTPS") + Rel(shell_host, mfe_gates, "Loads", "Module Federation") + Rel(shell_host, mfe_governance, "Loads", "Module Federation") - Rel(shell_host, api_gateway, "Llamadas API", "REST") + Rel(shell_host, api_gateway, "API calls", "REST") - Rel(api_gateway, process_orch, "Solicita transición", "HTTPS/REST") - Rel(api_gateway, ums, "Valida JWT", "HTTPS") + Rel(api_gateway, process_orch, "Requests transition", "HTTPS/REST") + Rel(api_gateway, ums, "Validates JWT", "HTTPS") - Rel(process_orch, gate_engine, "Solicita evaluación de Gate") - Rel(gate_engine, evidence_graph, "Consulta/Guarda Evidencia") - Rel(evidence_graph, provider_acl, "Normaliza datos de proveedores") + Rel(process_orch, gate_engine, "Requests Gate evaluation") + Rel(gate_engine, evidence_graph, "Queries/Stores Evidence") + Rel(evidence_graph, provider_acl, "Normalises provider data") - Rel(process_orch, single_db, "Escribe (schema por contexto)") - Rel(evidence_graph, single_db, "Guarda Linaje") + Rel(process_orch, single_db, "Writes (schema per context)") + Rel(evidence_graph, single_db, "Stores Lineage") ``` -## Nivel 3: Diagrama de Componentes (Control Plane Backend) +## Level 3: Component Diagram (Control Plane Backend) -Muestra los 9 Bounded Contexts lógicos (5 Phase Gates + 4 de soporte) que conforman el Monolito de Fase 1. +Shows the 9 logical Bounded Contexts (5 Phase Gates + 4 supporting) that make up the Phase 1 monolith. ```mermaid C4Component title Component diagram for Tracker Monolith Service Container_Boundary(backend_monolith, "Tracker Control Plane") { - Component(discovery_module, "Discovery Module", "Phase Gate 1", "Ideación, Canvas, validación estratégica (Build vs Compose)") - Component(design_module, "Design Module", "Phase Gate 2", "Contratos, ADRs, blueprints") + Component(discovery_module, "Discovery Module", "Phase Gate 1", "Ideation, Canvas, strategic validation (Build vs Compose)") + Component(design_module, "Design Module", "Phase Gate 2", "Contracts, ADRs, blueprints") Component(construction_module, "Construction Module", "Phase Gate 3", "Tracking, commits, Architecture Drift") - Component(qa_module, "QA Module", "Phase Gate 4", "Pruebas, calidad, CFR") - Component(release_module, "Release Module", "Phase Gate 5", "Despliegues, autorizaciones de release") + Component(qa_module, "QA Module", "Phase Gate 4", "Testing, quality, CFR") + Component(release_module, "Release Module", "Phase Gate 5", "Deployments, release authorisations") - Component(governance_module, "Governance Module", "Soporte", "SDLC execution, orquestación de agentes") - Component(artifacts_module, "Artifacts Module", "Soporte", "Definiciones de artefactos, Evidence Graph") - Component(metrics_module, "Metrics Module", "Soporte", "Scorecards asíncronos (DORA/SPACE)") - Component(integration_module, "Integration Module", "Soporte", "Ports & ACLs (Jira, GitHub, Langfuse)") + Component(governance_module, "Governance Module", "Supporting", "SDLC execution, agent orchestration") + Component(artifacts_module, "Artifacts Module", "Supporting", "Artifact definitions, Evidence Graph") + Component(metrics_module, "Metrics Module", "Supporting", "Asynchronous scorecards (DORA/SPACE)") + Component(integration_module, "Integration Module", "Supporting", "Ports & ACLs (Jira, GitHub, Langfuse)") - Component(event_bus, "Internal Event Bus", "In-Memory", "Comunicación asíncrona entre módulos (CQRS/Eventos)") + Component(event_bus, "Internal Event Bus", "In-Memory", "Asynchronous inter-module communication (CQRS/Events)") } - Container(api_gateway, "Governance API", "Nginx", "Llamadas entrantes (REST)") + Container(api_gateway, "Governance API", "Nginx", "Inbound calls (REST)") ContainerDb(single_db, "Relational Database", "PostgreSQL", "schema-per-context (T-047)") - Rel(api_gateway, discovery_module, "Ruta tráfico", "REST") - Rel(api_gateway, integration_module, "Ruta tráfico", "REST") + Rel(api_gateway, discovery_module, "Routes traffic", "REST") + Rel(api_gateway, integration_module, "Routes traffic", "REST") - Rel(integration_module, event_bus, "Publica eventos (ej. PR Merged)") - Rel(construction_module, event_bus, "Escucha eventos") + Rel(integration_module, event_bus, "Publishes events (e.g. PR Merged)") + Rel(construction_module, event_bus, "Listens for events") ``` diff --git a/reference/specs/discovery/DISCOVERY_CANVAS.md b/reference/specs/discovery/DISCOVERY_CANVAS.md index 588f8942..9b2d1ae3 100644 --- a/reference/specs/discovery/DISCOVERY_CANVAS.md +++ b/reference/specs/discovery/DISCOVERY_CANVAS.md @@ -2,31 +2,31 @@ > **Bilingual Navigation:** English (this document) · [Versión en Español](./DISCOVERY_CANVAS.es.md) -*Este documento es el artefacto oficial de entrada al flujo Spec-Driven. Toda iniciativa debe superar esta compuerta de viabilidad (ROI/KPIs) antes de autorizar el diseño arquitectónico.* - -## 1. Definición del Problema / Oportunidad -- **Problema:** Los ciclos de desarrollo de software tradicionales sufren de "Deriva Arquitectónica", falta de gobernanza en la codificación, y desalineación entre las fechas de negocio (Release Planner) y la calidad real del código (QA/Regresión). -- **Oportunidad:** Construir un SDLC AI-Native (Evolith Tracker) donde la IA genere y verifique código basado en contratos (Spec-as-Source), asegurando que el esfuerzo humano se concentre exclusivamente en el gobierno y orquestación. - -## 2. Propuesta de Valor -Una Suite de Ingeniería E2E que integra Discovery, Arquitectura, Tracking, QA y Release Management en un Monolito Progresivo Multi-Tenant, regido estrictamente por los estándares inmutables de `Evolith Core`. - -## 3. Retorno de Inversión (ROI) Justificado -- **Reducción de Costos:** Disminución del 40% en horas de refactorización por deuda técnica y deriva arquitectónica. -- **Eficiencia Operativa:** Eliminación del trabajo manual en la actualización de cronogramas de despliegue mediante el Motor de Contingencias (Re-Do Flow). -- **Time-to-Market:** Reducción del ciclo de entrega mediante la automatización del diseño técnico y QA por contratos. - -## 4. KPIs y Métricas de Éxito (DORA & SPACE) -- **Deployment Frequency:** Aumentar de despliegues semanales a despliegues diarios (On-Demand) gracias a los Quality Gates automatizados. -- **Lead Time for Changes:** Reducir el tiempo desde la ideación (Discovery) hasta producción en un 50%. -- **Architecture Adherence Index (Nuevo KPI):** Mantener un 100% de correlación entre especificaciones funcionales (Markdown), contratos técnicos (OpenAPI) y código físico. Cero deriva permitida. -- **Change Failure Rate:** Menor al 2% gracias a la integración profunda con `.harness` (Contract Testing). - -## 5. Riesgos y Supuestos (Gate Viability) -- **Riesgo:** Resistencia al cambio por parte de equipos acostumbrados a herramientas tradicionales (Jira, Trello) y desarrollo empírico sin contratos previos. -- **Mitigación:** Gobernanza forzada (System-level lock). Ningún código se despliega si no nace de una Spec y pasa el pipeline de `.harness`. -- **Supuesto:** Disponibilidad y estabilidad del servicio UMS para AuthN/AuthZ. - -## 6. Resolución del Agente PO (Compuerta) -[APROBADO] **ESTADO: APROBADO.** -El retorno de inversión justifica el costo. Los KPIs son medibles asíncronamente mediante CQRS. Se autoriza el avance a la fase de **Architecture Spec-Driven** para la definición de Contratos. +*This document is the official entry artifact into the Spec-Driven flow. Every initiative must clear this viability gate (ROI/KPIs) before architectural design is authorised.* + +## 1. Problem / Opportunity Definition +- **Problem:** Traditional software development cycles suffer from "Architecture Drift", a lack of governance over coding, and misalignment between business dates (Release Planner) and the real quality of the code (QA/Regression). +- **Opportunity:** Build an AI-Native SDLC (Evolith Tracker) where AI generates and verifies code from contracts (Spec-as-Source), ensuring human effort concentrates exclusively on governance and orchestration. + +## 2. Value Proposition +An end-to-end engineering suite integrating Discovery, Architecture, Tracking, QA and Release Management into a Progressive Multi-Tenant Monolith, governed strictly by the immutable standards of `Evolith Core`. + +## 3. Justified Return on Investment (ROI) +- **Cost reduction:** 40% fewer hours spent refactoring technical debt and architecture drift. +- **Operational efficiency:** Elimination of manual work updating deployment schedules, via the Contingency Engine (Re-Do Flow). +- **Time-to-Market:** Shorter delivery cycle through automation of technical design and contract-based QA. + +## 4. KPIs and Success Metrics (DORA & SPACE) +- **Deployment Frequency:** Move from weekly to daily (on-demand) deployments thanks to automated Quality Gates. +- **Lead Time for Changes:** Cut the time from ideation (Discovery) to production by 50%. +- **Architecture Adherence Index (new KPI):** Maintain 100% correlation between functional specifications (Markdown), technical contracts (OpenAPI) and physical code. Zero drift allowed. +- **Change Failure Rate:** Below 2%, thanks to deep integration with `.harness` (Contract Testing). + +## 5. Risks and Assumptions (Gate Viability) +- **Risk:** Resistance to change from teams used to traditional tooling (Jira, Trello) and to empirical development without prior contracts. +- **Mitigation:** Enforced governance (system-level lock). No code deploys unless it originates from a Spec and passes the `.harness` pipeline. +- **Assumption:** Availability and stability of the UMS service for AuthN/AuthZ. + +## 6. PO Agent Resolution (Gate) +[APPROVED] **STATUS: APPROVED.** +The return on investment justifies the cost. The KPIs are measurable asynchronously via CQRS. Advancement to the **Architecture Spec-Driven** phase is authorised for contract definition.