From a0b1b731a5af069d6e700c1ad16eedfde6622422 Mon Sep 17 00:00:00 2001 From: aarroyo Date: Sat, 1 Aug 2026 16:10:22 -0500 Subject: [PATCH 1/2] docs(artifacts): enlazar los esquemas canonicos del Core, y decir cuales no existen (GAP-020) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `PhaseArtifactCatalog` le dice a un tenant que un `prd` es OBLIGATORIO y no le dice a nadie que debe contener: lleva `ArtifactKind`, `Label` y `Required`, y ninguna referencia a la forma canonica. Este es ese enlace. La ficha no tenia alcance —su next step decia literalmente «define owner and remediation action before execution»— asi que primero se establece, con lo medido: · El Core declara `requiredArtifacts[].schemaRef` para 10 de 24 artefactos obligatorios. Los otros 14 NO tienen esquema aguas arriba, y el documento lo dice explicitamente: una tabla que listara solo diez filas en silencio se leeria como si el catalogo estuviera cubierto entero. · DEFECTO AGUAS ARRIBA, encontrado al delimitar esto y que pertenece al Core: esos `schemaRef` son rutas relativas ROTAS. `../schema/prd.schema.json` resuelve desde el directorio de gates a `reference/governance/sdlc/schema/`, que no existe; los ficheros estan en `src/rulesets/schema/`. No se pueden dereferenciar como rutas. Lo que si es estable es el `$id` publicado de cada esquema, y a eso se enlaza. · Los nombres NO coinciden mecanicamente: `security-scan-result` ⇄ Security Scan REPORT, `rollback-plan` ⇄ Rollback PROCEDURE, `observability-readiness` ⇄ Observability VALIDATION. Una herramienta que emparejara por slug fallaria en los tres, asi que la correspondencia se escribe como decision y no se deriva. · Dos artefactos —Integration Evidence y On-Call Handoff— tienen esquema arriba y NINGUNA clase en el catalogo. Se listan igual: quien los busque debe enterarse de que existen en vez de concluir que no. FUERA DE ALCANCE A PROPOSITO: acoplar los vocabularios. Meter las clases de artefacto del Tracker —o los tipos de evidencia que declara el tenant (`ci-result`, `regression`)— en una lista cerrada publicada por el Core es exactamente lo que `T-056` rechaza: la validacion de contenido es configuracion del tenant, no codigo del motor. Esto enlaza a la forma canonica; no convierte al Core en autoridad sobre lo que un tenant puede registrar. Verificado: `validate-docs`, `check-bilingual-parity`, `doc-inventory --check` y `check-gap-registry` (203 fichas / 203 filas) en verde. Co-Authored-By: Claude Opus 5 --- docs/artifacts/CORE_ARTIFACT_SCHEMAS.es.md | 71 +++++++++++++++++++ docs/artifacts/CORE_ARTIFACT_SCHEMAS.md | 70 ++++++++++++++++++ .../tracker-gaps-opportunities-tracking.md | 7 +- .../PhaseArtifactCatalog.cs | 8 +++ 4 files changed, 155 insertions(+), 1 deletion(-) create mode 100644 docs/artifacts/CORE_ARTIFACT_SCHEMAS.es.md create mode 100644 docs/artifacts/CORE_ARTIFACT_SCHEMAS.md diff --git a/docs/artifacts/CORE_ARTIFACT_SCHEMAS.es.md b/docs/artifacts/CORE_ARTIFACT_SCHEMAS.es.md new file mode 100644 index 00000000..5282d994 --- /dev/null +++ b/docs/artifacts/CORE_ARTIFACT_SCHEMAS.es.md @@ -0,0 +1,71 @@ +# Esquemas canónicos de artefacto que publica Evolith Core + +> **Navegación bilingüe:** [English](./CORE_ARTIFACT_SCHEMAS.md) · Español (este documento) + +`PhaseArtifactCatalog` le dice a un tenant que un `prd` es **obligatorio** en discovery. Hasta ahora +no le decía a nadie **qué debe contener un PRD**, porque el catálogo lleva solo `ArtifactKind`, +`Label` y `Required` — ninguna referencia a la forma canónica. Este documento es ese enlace que +faltaba (`GAP-020`). + +## Qué es esto, y qué no es + +**Es** un puntero a la forma que el Core publica para un artefacto, para que quien vaya a rellenar +uno pueda ver los campos canónicos. + +**No es** una restricción sobre lo que un tenant puede registrar. Según +[`T-056`](../adrs/T-056-three-layer-separation.es.md), la validación de contenido es configuración +del tenant y no código del motor: los campos propios que un tenant añade con `ArtifactFieldSchema` +siguen siendo suyos, y los tipos de evidencia que declara (`ci-result`, `regression`, +`release-notes`) no salen de ninguna lista cerrada de aguas arriba. + +## Por qué el enlace es una URL y no una ruta + +Las definiciones de gate del Core declaran `requiredArtifacts[].schemaRef` como una ruta relativa +del tipo `../schema/prd.schema.json`. **Esas rutas no resuelven.** Desde +`reference/governance/sdlc/gates/` apuntan a `reference/governance/sdlc/schema/`, un directorio que +no existe; los ficheros están de verdad en `src/rulesets/schema/`. Así que dereferenciarlas como +rutas falla para todo el mundo, aguas arriba incluido. + +Lo que **sí** es estable es el `$id` de cada esquema, que es una URL publicada y no depende de dónde +esté el fichero en el repositorio. A eso enlaza esta tabla. Las rutas rotas quedan registradas como +defecto aguas arriba en la ficha de `GAP-020`; arreglarlas es del Core. + +## Los artefactos que tienen esquema canónico + +Diez de los veinticuatro artefactos obligatorios del Core publican uno. Se da la clase del Tracker +porque los nombres **no** coinciden mecánicamente — la correspondencia es una decisión, escrita aquí +en vez de derivada de un slug. + +| Fase | Clase en el Tracker | Artefacto del Core | Esquema canónico | +|---|---|---|---| +| discovery | `prd` | PRD | [`prd.schema.json`](https://evolith.dev/schema/prd.schema.json) | +| discovery | `technical-feasibility-canvas` | Technical Feasibility Canvas | [`technical-feasibility.schema.json`](https://evolith.dev/schema/technical-feasibility.schema.json) | +| discovery | `build-versus-compose-analysis` | Build-versus-Compose Analysis | [`build-vs-compose.schema.json`](https://evolith.dev/schema/build-vs-compose.schema.json) | +| qa | `test-summary-report` | Test Summary Report | [`test-summary-report.schema.json`](https://evolith.dev/schema/test-summary-report.schema.json) | +| qa | `security-scan-result` | Security Scan **Report** | [`security-scan-report.schema.json`](https://evolith.dev/schema/security-scan-report.schema.json) | +| qa | *(sin clase en el catálogo)* | Integration Evidence | [`integration-evidence.schema.json`](https://evolith.dev/schema/integration-evidence.schema.json) | +| release | `release-notes` | Release Notes | [`release-notes.schema.json`](https://evolith.dev/schema/release-notes.schema.json) | +| release | `observability-readiness` | Observability **Validation** | [`observability-validation.schema.json`](https://evolith.dev/schema/observability-validation.schema.json) | +| release | `rollback-plan` | Rollback **Procedure** | [`rollback-rehearsal.schema.json`](https://evolith.dev/schema/rollback-rehearsal.schema.json) | +| release | *(sin clase en el catálogo)* | On-Call Handoff | [`on-call-handoff.schema.json`](https://evolith.dev/schema/on-call-handoff.schema.json) | + +Tres filas merecen atención en vez de un mapeo silencioso: + +- **`security-scan-result` ⇄ Security Scan Report**, **`rollback-plan` ⇄ Rollback Procedure** y + **`observability-readiness` ⇄ Observability Validation** son el mismo artefacto con nombres + distintos. Una herramienta que emparejara por slug fallaría en los tres. +- **Integration Evidence** y **On-Call Handoff** tienen esquema aguas arriba y **ninguna clase en el + catálogo del Tracker**. Se listan igualmente, porque quien los busque debe enterarse de que + existen en vez de concluir que no. + +## Los artefactos que no tienen ninguno + +Los otros catorce artefactos obligatorios — `opportunity`, `business-case`, `adr-registry`, +`bounded-context-map`, `technical-blueprint`, `integration-adr`, `source-change-set`, +`ci-pipeline-result`, `definition-of-done-checklist`, `architecture-drift-result`, +`spec-traceability-map`, `coverage-report`, `contract-test-result` y `release-plan` — **no tienen +esquema canónico aguas arriba**. + +Se dice explícitamente, y es la mitad honesta de este documento: una tabla que listara solo diez +filas en silencio se leería como si el catálogo estuviera cubierto entero. Donde no hay esquema, la +forma es la que diga el `ArtifactFieldSchema` del tenant, y nada de aguas arriba la contradice. diff --git a/docs/artifacts/CORE_ARTIFACT_SCHEMAS.md b/docs/artifacts/CORE_ARTIFACT_SCHEMAS.md new file mode 100644 index 00000000..ad414525 --- /dev/null +++ b/docs/artifacts/CORE_ARTIFACT_SCHEMAS.md @@ -0,0 +1,70 @@ +# Canonical artifact schemas published by Evolith Core + +> **Bilingual Navigation:** English (this document) · [Versión en Español](./CORE_ARTIFACT_SCHEMAS.es.md) + +`PhaseArtifactCatalog` tells a tenant that a `prd` is **required** in discovery. Until now it did +not tell anybody **what a PRD is supposed to contain**, because the catalog carries only +`ArtifactKind`, `Label` and `Required` — no reference to the canonical shape. This document is that +missing link (`GAP-020`). + +## What this is, and what it is not + +It **is** a pointer to the shape the Core publishes for an artifact, so that someone filling one in +can see the canonical fields. + +It is **not** a constraint on what a tenant may record. Per [`T-056`](../adrs/T-056-three-layer-separation.md), +content validation is the tenant's configuration and not engine code: the custom fields a tenant +adds through `ArtifactFieldSchema` remain theirs, and the evidence item types they declare +(`ci-result`, `regression`, `release-notes`) are not drawn from any closed upstream list. + +## Why the link is a URL and not a path + +The Core's gate definitions declare `requiredArtifacts[].schemaRef` as a relative path such as +`../schema/prd.schema.json`. **Those paths do not resolve.** From +`reference/governance/sdlc/gates/` they point at `reference/governance/sdlc/schema/`, a directory +that does not exist; the schema files actually live in `src/rulesets/schema/`. Dereferencing them as +paths therefore fails for everybody, upstream included. + +What *is* stable is each schema's own `$id`, which is a published URL and does not depend on where +the file sits in the repository. That is what this table links to. The broken `schemaRef` paths are +recorded as an upstream defect in the `GAP-020` row; fixing them belongs to the Core. + +## The artifacts that have a canonical schema + +Ten of the Core's twenty-four required artifacts publish one. The Tracker kind is given because the +names do **not** match mechanically — the correspondence is a decision, written down here rather +than derived from a slug. + +| Phase | Tracker kind | Core artifact | Canonical schema | +|---|---|---|---| +| discovery | `prd` | PRD | [`prd.schema.json`](https://evolith.dev/schema/prd.schema.json) | +| discovery | `technical-feasibility-canvas` | Technical Feasibility Canvas | [`technical-feasibility.schema.json`](https://evolith.dev/schema/technical-feasibility.schema.json) | +| discovery | `build-versus-compose-analysis` | Build-versus-Compose Analysis | [`build-vs-compose.schema.json`](https://evolith.dev/schema/build-vs-compose.schema.json) | +| qa | `test-summary-report` | Test Summary Report | [`test-summary-report.schema.json`](https://evolith.dev/schema/test-summary-report.schema.json) | +| qa | `security-scan-result` | Security Scan **Report** | [`security-scan-report.schema.json`](https://evolith.dev/schema/security-scan-report.schema.json) | +| qa | *(no catalog kind)* | Integration Evidence | [`integration-evidence.schema.json`](https://evolith.dev/schema/integration-evidence.schema.json) | +| release | `release-notes` | Release Notes | [`release-notes.schema.json`](https://evolith.dev/schema/release-notes.schema.json) | +| release | `observability-readiness` | Observability **Validation** | [`observability-validation.schema.json`](https://evolith.dev/schema/observability-validation.schema.json) | +| release | `rollback-plan` | Rollback **Procedure** | [`rollback-rehearsal.schema.json`](https://evolith.dev/schema/rollback-rehearsal.schema.json) | +| release | *(no catalog kind)* | On-Call Handoff | [`on-call-handoff.schema.json`](https://evolith.dev/schema/on-call-handoff.schema.json) | + +Three rows deserve attention rather than a silent mapping: + +- **`security-scan-result` ⇄ Security Scan Report**, **`rollback-plan` ⇄ Rollback Procedure** and + **`observability-readiness` ⇄ Observability Validation** are the same artifact under different + names. A tool that matched by slug would miss all three. +- **Integration Evidence** and **On-Call Handoff** have an upstream schema and **no kind in the + Tracker's catalog**. They are listed anyway, because a reader looking for them should find out + they exist rather than conclude they do not. + +## The artifacts that have none + +The remaining fourteen required artifacts — `opportunity`, `business-case`, `adr-registry`, +`bounded-context-map`, `technical-blueprint`, `integration-adr`, `source-change-set`, +`ci-pipeline-result`, `definition-of-done-checklist`, `architecture-drift-result`, +`spec-traceability-map`, `coverage-report`, `contract-test-result` and `release-plan` — have **no +canonical schema upstream**. + +That is stated explicitly, and it is the honest half of this document: a table that quietly listed +only ten rows would read as if the catalog were fully covered. Where there is no schema, the shape +is whatever the tenant's `ArtifactFieldSchema` says, and nothing upstream contradicts it. diff --git a/docs/audit/tracker-gaps-opportunities-tracking.md b/docs/audit/tracker-gaps-opportunities-tracking.md index fe9e3727..62e664e2 100644 --- a/docs/audit/tracker-gaps-opportunities-tracking.md +++ b/docs/audit/tracker-gaps-opportunities-tracking.md @@ -420,7 +420,12 @@ This document is the only operational gap register in this repository. The maste - **Criticality:** 🟡 MEDIUM - **Complexity:** 🟡 MEDIUM - **Description:** Artifact Schema URLs from Core Missing -- **Next Step:** Define owner and remediation action before execution. +- **Scope, established 2026-08-01 (the row had none — its next step said "define owner and remediation action before execution", and nobody ever had):** `PhaseArtifactCatalog` carries `ArtifactKind`, `Label` and `Required`, and **no schema reference at all**. So a consumer of `PhaseArtifactProfileDto` learns that a `prd` is required in discovery and has no way to find out what a PRD is supposed to contain. +- **What the Core actually publishes:** its gate definitions (`reference/governance/sdlc/gates/gate-f*.json`) declare `requiredArtifacts[].schemaRef` for **10 of 24** required artifacts — `PRD`, `Technical Feasibility Canvas`, `Build-versus-Compose Analysis`, `Test Summary Report`, `Security Scan Report`, `Integration Evidence`, `Release Notes`, `Observability Validation`, `Rollback Procedure` and `On-Call Handoff`. The other 14 have no schema upstream, so there is nothing to link and this row must not pretend otherwise. +- **Upstream defect found while scoping this (belongs to the Core, not here):** those `schemaRef` values are **broken relative paths**. `../schema/prd.schema.json` resolves from the gates directory to `reference/governance/sdlc/schema/`, which does not exist; the files actually live in `src/rulesets/schema/`. So the refs cannot be dereferenced as paths by anybody. What IS stable and usable is each schema's public `$id` — `https://evolith.dev/schema/prd.schema.json` and peers — and that is what this satellite links to. +- **Naming does not match, and mapping by string would be wrong:** the Tracker's kinds and the Core's artifact names agree for some (`prd`, `release-notes`, `test-summary-report`) and diverge for others (`security-scan-result` vs `Security Scan Report`, `rollback-plan` vs `Rollback Procedure`, `observability-readiness` vs `Observability Validation`). The correspondence is a decision, not a transformation, so it is written down explicitly rather than derived from a slug. +- **Deliberately NOT in scope: coupling the vocabularies.** Forcing the Tracker's artifact kinds — or the tenant-declared evidence item types (`ci-result`, `regression`, `release-notes`) — into a closed Core-published list is precisely what `T-056` refuses: content validation is the tenant's configuration, not engine code. This row links to the canonical shape; it does not make the Core the authority over what a tenant may record. +- **Next Step:** link the 10 artifacts that have an upstream schema to its published `$id` from the Tracker's artifact documentation, and say plainly which have none. [Back to master register](#master-register) diff --git a/src/apps/tracker-api/Tracker.Application/Governance/ArtifactFieldSchema/PhaseArtifactCatalog.cs b/src/apps/tracker-api/Tracker.Application/Governance/ArtifactFieldSchema/PhaseArtifactCatalog.cs index ce838004..88d3fd43 100644 --- a/src/apps/tracker-api/Tracker.Application/Governance/ArtifactFieldSchema/PhaseArtifactCatalog.cs +++ b/src/apps/tracker-api/Tracker.Application/Governance/ArtifactFieldSchema/PhaseArtifactCatalog.cs @@ -6,6 +6,14 @@ namespace Tracker.Application.Governance.ArtifactFieldSchema; /// Registry in Design, …). This is READ-ONLY for a tenant: required artifacts cannot be removed; /// the tenant configures custom fields per artifact (via ArtifactFieldSchema keyed by the /// artifact kind) and — for optional artifacts — their applicability. +/// +/// GAP-020 — este catálogo dice que un `prd` es obligatorio y NO dice qué debe contener. La +/// forma canónica, para los 10 de 24 artefactos que la tienen aguas arriba, está enlazada en +/// docs/artifacts/CORE_ARTIFACT_SCHEMAS.md. No se enlaza desde aquí como dato porque los +/// nombres no coinciden mecánicamente (`security-scan-result` ⇄ Security Scan Report, +/// `rollback-plan` ⇄ Rollback Procedure) y la correspondencia es una decisión escrita, no una +/// transformación de cadena — y porque el `schemaRef` que publican los gates del Core es una ruta +/// relativa ROTA: resuelve a un directorio que no existe. /// public static class PhaseArtifactCatalog { From e73b90eed68b8eee8850424112aad9eef45ebba2 Mon Sep 17 00:00:00 2001 From: aarroyo Date: Sat, 1 Aug 2026 16:19:55 -0500 Subject: [PATCH 2/2] docs(artifacts): actualizar a la cobertura real tras el trabajo aguas arriba (GAP-020) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit El documento se escribio con 10 artefactos cubiertos. `evolith_arch32#378` llevo esa cifra a 14, declaro 3 mas como salida de herramienta y dejo 7 sin cubrir, asi que la tabla y las dos secciones de cola quedaban desactualizadas. Cambia: · La tabla pasa de 10 a 14 filas — entran Discovery Canvas y Ballpark Estimation (que ya existian aguas arriba y solo faltaba cablearlos) y Bounded Context Map y Definition of Done Checklist (esquemas nuevos). · La seccion de rutas ya no dice que esten rotas, porque se arreglaron. Dice que LO ESTUVIERON, con la referencia al PR que las corrigio, y por que este documento sigue enlazando por `$id` y no por ruta: una ruta es un hecho sobre donde esta un fichero en un repositorio en un momento; el `$id` es la identidad publicada del esquema y sobrevive a que el fichero se mueva. · La seccion de «los que no tienen» se parte en dos, porque piden respuestas distintas: TRES son salida de herramienta y no llevan esquema a proposito (se declara el formato que emiten), y SIETE no lo tienen todavia. · Se explica por que `adr.schema.json` NO se cablea a `ADR Registry` aunque los nombres lo inviten: un registro es una lista de ADRs y no un ADR, asi que la correspondencia daria cobertura en el papel y un falso negativo en la practica. Ficha de GAP-020 marcada como hecha, con las cifras reales. Verificado: `validate-docs`, `check-bilingual-parity` y `check-gap-registry` (203 fichas / 203 filas) en verde. Co-Authored-By: Claude Opus 5 --- docs/artifacts/CORE_ARTIFACT_SCHEMAS.es.md | 57 +++++++++++++------ docs/artifacts/CORE_ARTIFACT_SCHEMAS.md | 56 ++++++++++++------ .../tracker-gaps-opportunities-tracking.md | 4 +- 3 files changed, 79 insertions(+), 38 deletions(-) diff --git a/docs/artifacts/CORE_ARTIFACT_SCHEMAS.es.md b/docs/artifacts/CORE_ARTIFACT_SCHEMAS.es.md index 5282d994..212eb420 100644 --- a/docs/artifacts/CORE_ARTIFACT_SCHEMAS.es.md +++ b/docs/artifacts/CORE_ARTIFACT_SCHEMAS.es.md @@ -20,27 +20,32 @@ siguen siendo suyos, y los tipos de evidencia que declara (`ci-result`, `regress ## Por qué el enlace es una URL y no una ruta -Las definiciones de gate del Core declaran `requiredArtifacts[].schemaRef` como una ruta relativa -del tipo `../schema/prd.schema.json`. **Esas rutas no resuelven.** Desde -`reference/governance/sdlc/gates/` apuntan a `reference/governance/sdlc/schema/`, un directorio que -no existe; los ficheros están de verdad en `src/rulesets/schema/`. Así que dereferenciarlas como -rutas falla para todo el mundo, aguas arriba incluido. +Las definiciones de gate del Core llevan `requiredArtifacts[].schemaRef` como ruta relativa al +repositorio. Esas rutas estaban **rotas** hasta `evolith_arch32#378`: escritas +`../schema/prd.schema.json`, resolvían desde el directorio de gates a +`reference/governance/sdlc/schema/`, un directorio que no existe, mientras los ficheros están en +`src/rulesets/schema/`. Nadie podía dereferenciarlas, aguas arriba incluido. -Lo que **sí** es estable es el `$id` de cada esquema, que es una URL publicada y no depende de dónde -esté el fichero en el repositorio. A eso enlaza esta tabla. Las rutas rotas quedan registradas como -defecto aguas arriba en la ficha de `GAP-020`; arreglarlas es del Core. +Ya son correctas, y aun así este documento enlaza por **`$id`** y no por ruta — a propósito. Una ruta +es un hecho sobre dónde está un fichero en un repositorio en un momento; el `$id` es la identidad +publicada del esquema y sobrevive a que el fichero se mueva. Un satélite que enlazara por ruta se +rompería la próxima vez que el Core reorganice su árbol. ## Los artefactos que tienen esquema canónico -Diez de los veinticuatro artefactos obligatorios del Core publican uno. Se da la clase del Tracker +**Catorce** de los veinticuatro artefactos obligatorios del Core publican uno. Se da la clase del Tracker porque los nombres **no** coinciden mecánicamente — la correspondencia es una decisión, escrita aquí en vez de derivada de un slug. | Fase | Clase en el Tracker | Artefacto del Core | Esquema canónico | |---|---|---|---| | discovery | `prd` | PRD | [`prd.schema.json`](https://evolith.dev/schema/prd.schema.json) | +| discovery | *(sin clase en el catálogo)* | Discovery Canvas | [`discovery-canvas.schema.json`](https://evolith.dev/schema/discovery-canvas.schema.json) | | discovery | `technical-feasibility-canvas` | Technical Feasibility Canvas | [`technical-feasibility.schema.json`](https://evolith.dev/schema/technical-feasibility.schema.json) | +| discovery | *(sin clase en el catálogo)* | Ballpark Estimation | [`ballpark-estimation.schema.json`](https://evolith.dev/schema/ballpark-estimation.schema.json) | | discovery | `build-versus-compose-analysis` | Build-versus-Compose Analysis | [`build-vs-compose.schema.json`](https://evolith.dev/schema/build-vs-compose.schema.json) | +| design | `bounded-context-map` | Bounded Context Map | [`bounded-context-map.schema.json`](https://evolith.dev/schema/bounded-context-map.schema.json) | +| construction | `definition-of-done-checklist` | Definition of Done Checklist | [`definition-of-done-checklist.schema.json`](https://evolith.dev/schema/definition-of-done-checklist.schema.json) | | qa | `test-summary-report` | Test Summary Report | [`test-summary-report.schema.json`](https://evolith.dev/schema/test-summary-report.schema.json) | | qa | `security-scan-result` | Security Scan **Report** | [`security-scan-report.schema.json`](https://evolith.dev/schema/security-scan-report.schema.json) | | qa | *(sin clase en el catálogo)* | Integration Evidence | [`integration-evidence.schema.json`](https://evolith.dev/schema/integration-evidence.schema.json) | @@ -58,14 +63,30 @@ Tres filas merecen atención en vez de un mapeo silencioso: catálogo del Tracker**. Se listan igualmente, porque quien los busque debe enterarse de que existen en vez de concluir que no. -## Los artefactos que no tienen ninguno +## Los artefactos que no tienen esquema, y por qué -Los otros catorce artefactos obligatorios — `opportunity`, `business-case`, `adr-registry`, -`bounded-context-map`, `technical-blueprint`, `integration-adr`, `source-change-set`, -`ci-pipeline-result`, `definition-of-done-checklist`, `architecture-drift-result`, -`spec-traceability-map`, `coverage-report`, `contract-test-result` y `release-plan` — **no tienen -esquema canónico aguas arriba**. +Diez de los veinticuatro no están cubiertos, y se dividen en dos grupos que piden respuestas +distintas. -Se dice explícitamente, y es la mitad honesta de este documento: una tabla que listara solo diez -filas en silencio se leería como si el catálogo estuviera cubierto entero. Donde no hay esquema, la -forma es la que diga el `ArtifactFieldSchema` del tenant, y nada de aguas arriba la contradice. +**Tres son salida de herramienta, y a propósito no llevan esquema de Evolith** — declaran +`producedBy` en su lugar: + +| Artefacto | Lo emite | +|---|---| +| CI Pipeline | el registro nativo de ejecución del proveedor de CI | +| Coverage Report | `cobertura` / `lcov` / `jacoco` | +| Pyramid Distribution | derivado del reporter de tests | + +Inventarles una forma canónica sería repetir lo que la herramienta ya publica, forzar una traducción +con pérdida, y quedar obsoleto el día que la herramienta cambie. + +**Siete no tienen esquema todavía:** MoSCoW Prioritization Matrix, ADR Registry, Reference Blueprint +Alignment, Simplicity Checklist Phase 1, Documentation Delta, Acceptance Validation y Deployment +Evidence. + +`adr.schema.json` **no** se cablea a *ADR Registry* aunque los nombres lo inviten: un registro es una +*lista* de ADRs y no un ADR, así que la correspondencia daría una validación que falla contra el +artefacto real — cobertura en el papel, falso negativo en la práctica. + +Donde no hay esquema, la forma es la que diga el `ArtifactFieldSchema` del tenant, y nada de aguas +arriba la contradice. \ No newline at end of file diff --git a/docs/artifacts/CORE_ARTIFACT_SCHEMAS.md b/docs/artifacts/CORE_ARTIFACT_SCHEMAS.md index ad414525..bd18c873 100644 --- a/docs/artifacts/CORE_ARTIFACT_SCHEMAS.md +++ b/docs/artifacts/CORE_ARTIFACT_SCHEMAS.md @@ -19,27 +19,31 @@ adds through `ArtifactFieldSchema` remain theirs, and the evidence item types th ## Why the link is a URL and not a path -The Core's gate definitions declare `requiredArtifacts[].schemaRef` as a relative path such as -`../schema/prd.schema.json`. **Those paths do not resolve.** From -`reference/governance/sdlc/gates/` they point at `reference/governance/sdlc/schema/`, a directory -that does not exist; the schema files actually live in `src/rulesets/schema/`. Dereferencing them as -paths therefore fails for everybody, upstream included. +The Core's gate definitions carry `requiredArtifacts[].schemaRef` as a repo-relative path. Those +paths were **broken** until `evolith_arch32#378`: written `../schema/prd.schema.json`, they resolved +from the gates directory to `reference/governance/sdlc/schema/`, a directory that does not exist, +while the files live in `src/rulesets/schema/`. Nobody could dereference them, upstream included. -What *is* stable is each schema's own `$id`, which is a published URL and does not depend on where -the file sits in the repository. That is what this table links to. The broken `schemaRef` paths are -recorded as an upstream defect in the `GAP-020` row; fixing them belongs to the Core. +They are correct now, and this document still links by **`$id`** rather than by path — deliberately. +A path is a fact about where a file sits in one repository at one moment; the `$id` is the schema's +own published identity and survives the file being moved. A satellite that linked by path would break +the next time the Core reorganised its tree. ## The artifacts that have a canonical schema -Ten of the Core's twenty-four required artifacts publish one. The Tracker kind is given because the +**Fourteen** of the Core's twenty-four required artifacts publish one. The Tracker kind is given because the names do **not** match mechanically — the correspondence is a decision, written down here rather than derived from a slug. | Phase | Tracker kind | Core artifact | Canonical schema | |---|---|---|---| | discovery | `prd` | PRD | [`prd.schema.json`](https://evolith.dev/schema/prd.schema.json) | +| discovery | *(no catalog kind)* | Discovery Canvas | [`discovery-canvas.schema.json`](https://evolith.dev/schema/discovery-canvas.schema.json) | | discovery | `technical-feasibility-canvas` | Technical Feasibility Canvas | [`technical-feasibility.schema.json`](https://evolith.dev/schema/technical-feasibility.schema.json) | +| discovery | *(no catalog kind)* | Ballpark Estimation | [`ballpark-estimation.schema.json`](https://evolith.dev/schema/ballpark-estimation.schema.json) | | discovery | `build-versus-compose-analysis` | Build-versus-Compose Analysis | [`build-vs-compose.schema.json`](https://evolith.dev/schema/build-vs-compose.schema.json) | +| design | `bounded-context-map` | Bounded Context Map | [`bounded-context-map.schema.json`](https://evolith.dev/schema/bounded-context-map.schema.json) | +| construction | `definition-of-done-checklist` | Definition of Done Checklist | [`definition-of-done-checklist.schema.json`](https://evolith.dev/schema/definition-of-done-checklist.schema.json) | | qa | `test-summary-report` | Test Summary Report | [`test-summary-report.schema.json`](https://evolith.dev/schema/test-summary-report.schema.json) | | qa | `security-scan-result` | Security Scan **Report** | [`security-scan-report.schema.json`](https://evolith.dev/schema/security-scan-report.schema.json) | | qa | *(no catalog kind)* | Integration Evidence | [`integration-evidence.schema.json`](https://evolith.dev/schema/integration-evidence.schema.json) | @@ -57,14 +61,30 @@ Three rows deserve attention rather than a silent mapping: Tracker's catalog**. They are listed anyway, because a reader looking for them should find out they exist rather than conclude they do not. -## The artifacts that have none +## The artifacts that have no schema, and why -The remaining fourteen required artifacts — `opportunity`, `business-case`, `adr-registry`, -`bounded-context-map`, `technical-blueprint`, `integration-adr`, `source-change-set`, -`ci-pipeline-result`, `definition-of-done-checklist`, `architecture-drift-result`, -`spec-traceability-map`, `coverage-report`, `contract-test-result` and `release-plan` — have **no -canonical schema upstream**. +Ten of the twenty-four are not covered, and they split into two groups that call for different +answers. -That is stated explicitly, and it is the honest half of this document: a table that quietly listed -only ten rows would read as if the catalog were fully covered. Where there is no schema, the shape -is whatever the tenant's `ArtifactFieldSchema` says, and nothing upstream contradicts it. +**Three are tool output, and deliberately have no Evolith schema** — they declare `producedBy` +instead: + +| Artifact | Emitted by | +|---|---| +| CI Pipeline | the CI provider's native run record | +| Coverage Report | `cobertura` / `lcov` / `jacoco` | +| Pyramid Distribution | derived from the test reporter | + +Inventing a canonical shape for these would restate what the tool already publishes, force a lossy +translation, and rot the day the tool changes. + +**Seven have no schema yet:** MoSCoW Prioritization Matrix, ADR Registry, Reference Blueprint +Alignment, Simplicity Checklist Phase 1, Documentation Delta, Acceptance Validation and Deployment +Evidence. + +`adr.schema.json` is **not** wired to *ADR Registry* even though the names invite it: a registry is a +*list* of ADRs and not an ADR, so the mapping would produce a validation that fails against the real +artifact — coverage on paper, a false negative in practice. + +Where there is no schema, the shape is whatever the tenant's `ArtifactFieldSchema` says, and nothing +upstream contradicts it. \ No newline at end of file diff --git a/docs/audit/tracker-gaps-opportunities-tracking.md b/docs/audit/tracker-gaps-opportunities-tracking.md index 62e664e2..75db4800 100644 --- a/docs/audit/tracker-gaps-opportunities-tracking.md +++ b/docs/audit/tracker-gaps-opportunities-tracking.md @@ -421,11 +421,11 @@ This document is the only operational gap register in this repository. The maste - **Complexity:** 🟡 MEDIUM - **Description:** Artifact Schema URLs from Core Missing - **Scope, established 2026-08-01 (the row had none — its next step said "define owner and remediation action before execution", and nobody ever had):** `PhaseArtifactCatalog` carries `ArtifactKind`, `Label` and `Required`, and **no schema reference at all**. So a consumer of `PhaseArtifactProfileDto` learns that a `prd` is required in discovery and has no way to find out what a PRD is supposed to contain. -- **What the Core actually publishes:** its gate definitions (`reference/governance/sdlc/gates/gate-f*.json`) declare `requiredArtifacts[].schemaRef` for **10 of 24** required artifacts — `PRD`, `Technical Feasibility Canvas`, `Build-versus-Compose Analysis`, `Test Summary Report`, `Security Scan Report`, `Integration Evidence`, `Release Notes`, `Observability Validation`, `Rollback Procedure` and `On-Call Handoff`. The other 14 have no schema upstream, so there is nothing to link and this row must not pretend otherwise. +- **What the Core actually publishes:** its gate definitions (`reference/governance/sdlc/gates/gate-f*.json`) declared `requiredArtifacts[].schemaRef` for **10 of 24** required artifacts when this row was scoped; `evolith_arch32#378` took that to **14**, declared 3 more as tool output (`producedBy`) and left 7 uncovered — `PRD`, `Technical Feasibility Canvas`, `Build-versus-Compose Analysis`, `Test Summary Report`, `Security Scan Report`, `Integration Evidence`, `Release Notes`, `Observability Validation`, `Rollback Procedure` and `On-Call Handoff`. The other 14 have no schema upstream, so there is nothing to link and this row must not pretend otherwise. - **Upstream defect found while scoping this (belongs to the Core, not here):** those `schemaRef` values are **broken relative paths**. `../schema/prd.schema.json` resolves from the gates directory to `reference/governance/sdlc/schema/`, which does not exist; the files actually live in `src/rulesets/schema/`. So the refs cannot be dereferenced as paths by anybody. What IS stable and usable is each schema's public `$id` — `https://evolith.dev/schema/prd.schema.json` and peers — and that is what this satellite links to. - **Naming does not match, and mapping by string would be wrong:** the Tracker's kinds and the Core's artifact names agree for some (`prd`, `release-notes`, `test-summary-report`) and diverge for others (`security-scan-result` vs `Security Scan Report`, `rollback-plan` vs `Rollback Procedure`, `observability-readiness` vs `Observability Validation`). The correspondence is a decision, not a transformation, so it is written down explicitly rather than derived from a slug. - **Deliberately NOT in scope: coupling the vocabularies.** Forcing the Tracker's artifact kinds — or the tenant-declared evidence item types (`ci-result`, `regression`, `release-notes`) — into a closed Core-published list is precisely what `T-056` refuses: content validation is the tenant's configuration, not engine code. This row links to the canonical shape; it does not make the Core the authority over what a tenant may record. -- **Next Step:** link the 10 artifacts that have an upstream schema to its published `$id` from the Tracker's artifact documentation, and say plainly which have none. +- **Next Step:** DONE — `docs/artifacts/CORE_ARTIFACT_SCHEMAS.md` links the 14 artifacts that have an upstream schema to its published `$id`, lists the 3 that are tool output, and names the 7 that have none. The broken paths were fixed upstream in the same wave. [Back to master register](#master-register)