@rlabs-cl/arketum 0.0.0-stage → 1.0.1

package/catalogo-de-ejemplo/arquetipos/levantamiento-de-infraestructura.yaml

@@ -0,0 +1,117 @@
+# Levantamiento de infraestructura.
+#
+# Artefacto de trabajo del carril `despliegue`: va en un paso con la marca
+# `pendientes`, lo llevan los papeles de la fase 1 (el analista habla con la
+# persona; el arquitecto deduce lo técnico, propone el modo y redacta los
+# pendientes) y alimenta al paso de sistema y al de evidencia `preparado`.
+# Indaga: dónde se despliega, en qué entornos, con qué accesos y
+# configuraciones, quién opera, hasta dónde se automatiza y cómo se sabe que
+# funciona. No rellena una lista.
+#
+# Lo que no se puede responder en la sesión es un `pendiente` (L1): Arketum
+# genera el cuestionario, la unidad se pausa y las respuestas entran en el
+# último nivel (L2), hijas de su pendiente. El vocabulario de los pendientes
+# (`entorno`, `pendiente`, `respuesta`, `referencia`) es del núcleo.
+name: levantamiento-de-infraestructura
+version: 1.0.0
+description: >-
+  Levantamiento completo de la infraestructura donde se despliega un sistema: alcance y entornos, accesos, configuración, operación, automatización y verificación, con lo que falta como pendientes que la persona trae fuera de la sesión. Termina en el modo de despliegue y en los requisitos técnicos de cada entorno. Elígelo antes de preparar un despliegue; para pedir funcionalidad corresponde un PRD.
+tags: [proceso, despliegue, infraestructura]
+
+kinds:
+  - name: desplegable
+    describes: "alcance (L0): un artefacto del proyecto que se despliega"
+  - name: entorno
+    describes: "alcance (L0): un entorno donde se despliega (`local`, `staging`, `produccion`), con su id como slug y `despliega: si|no` (si esta unidad lo despliega o solo lo prepara)"
+  - name: tema
+    describes: "lo que hay que saber de un entorno (L1), con su rol: `acceso`, `configuracion`, `operacion`, `automatizacion`, `verificacion`, u otro (`red`, `datos`, `coste`, `cumplimiento`, `recuperacion`…)"
+  - name: pendiente
+    describes: "lo que no se puede responder en la sesión (L1): `que`, `porque` (obligatorio), `donde`, `quien`, `respuesta` (`valor`, `referencia` o `confirmacion`) y `antes_de` (`preparar` o `desplegar:<entorno>`)"
+  - name: requisito
+    describes: "lo acordado (L2), como requisito: `tecnico` (con `entorno` el de cada entorno, con `modo` el del modo) o `decision` (con `antes_de: desplegar:<entorno>` la de un pendiente de antes de desplegar)"
+  - name: respuesta
+    describes: "la respuesta a un pendiente de antes de preparar (L2): `de` (el pendiente) y su `valor`, su `referencia` o su `confirmacion`"
+  - name: referencia
+    describes: "dónde vive un secreto que el despliegue necesita (L2): `referencia: <esquema>:<ruta>` y su verificación (`evidence: execution`, `expect: success`, `on: entorno`), o `verificable: no` con su `motivo`"
+  - name: documento
+    describes: el fichero del levantamiento, en la carpeta de trabajo del paso (nunca el cuestionario, que va fuera del repositorio)
+
+extractors:
+  - mechanism: path
+    kind: documento
+    pattern: "<nombre>.md"
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: ALCANCE
+    instruction: >
+      Declara qué se despliega (un `desplegable` por artefacto del proyecto) y en
+      qué entornos (un `entorno` por entorno, con su id como slug: `local`,
+      `staging`, `produccion`). Pregúntale a la persona dónde quiere tenerlo
+      funcionando y quién lo va a usar en cada sitio; no propongas todavía cómo.
+      Cada `entorno` lleva el atributo `despliega`: `si` si esta unidad lo
+      despliega y lo deja funcionando (entonces la unidad lleva el hito
+      `despliegue <entorno>`), `no` si solo lo prepara. Sale de lo que pide la
+      persona, no de lo que te resulte más cómodo: si dice «quiero verla
+      funcionando en mi portátil ya», `local` lleva `despliega: si`. Como mucho
+      un entorno se despliega en una unidad; los demás, en otra.
+  - id: L1
+    requiredRoles: [acceso, configuracion, operacion, automatizacion, verificacion]
+    title: LO QUE HAY QUE SABER
+    instruction: >
+      Indaga cada entorno: cada `entorno` del alcance tiene hijos aquí, y entre
+      todos cubren al menos los roles `acceso` (cuentas, permisos, credenciales:
+      dónde viven), `configuracion` (variables, dominios, puertos, registros de
+      imágenes), `operacion` (quién lo opera, cómo se actualiza, qué pasa si se
+      cae), `automatizacion` (hasta dónde se automatiza y qué despliega cada
+      cual) y `verificacion` (cómo se sabe que funciona después de desplegar).
+      La lista NO está cerrada: pregunta qué más hay (`red`, `datos`, `coste`,
+      `cumplimiento`, `recuperacion`…) y decláralo con su rol. En lo técnico de
+      infraestructura esta instrucción manda sobre el texto del papel: el
+      arquitecto sí nombra tecnologías, puertos, rutas y comandos. Lo que no se
+      puede responder en la sesión (un acceso que hay que pedir, un dato de otro
+      equipo) es un `pendiente`, hijo de su entorno, con `que`, `porque`
+      (obligatorio: para qué hace falta), `donde` (otro equipo, la consola del
+      proveedor, un contrato), `quien` (quién lo trae), `respuesta` (`valor` si
+      es un dato que no es secreto, `referencia` si es dónde vive un secreto,
+      nunca el secreto, o `confirmacion` si es algo hecho) y `antes_de`
+      (`preparar` si sin él no se puede preparar, o `desplegar:<entorno>` si
+      solo hace falta antes de desplegar ese entorno). Al aceptarse este nivel
+      con pendientes, Arketum devuelve el cuestionario.
+    fanout:
+      min: 5
+      max: 40
+  - id: L2
+    requiredRoles: []
+    title: LO ACORDADO
+    instruction: >
+      Declara el alcance acordado como requisitos (atributos `tipo`,
+      `requisito`, `titulo`, `sale_de` —la frase de la persona o el requisito
+      del que se deduce—, `porque` en un `tecnico`, `aceptacion` y `artefacto`:
+      el id del artefacto de despliegue del proyecto, donde viven). Un `tecnico`
+      por entorno con el atributo `entorno` (los entornos del proyecto son los
+      de esos técnicos), y el modo como un `tecnico` con el atributo `modo`
+      (`compose`, `pipeline`, `script` u otro) y su `porque`, que la persona
+      confirma en el gate; los demás técnicos con su `porque` («se automatiza
+      hasta staging», «producción la despliega operaciones con el script»). Las
+      `decision` que siguen abiertas. Una `referencia` por secreto que el
+      despliegue necesita (`referencia: <esquema>:<ruta>`; habituales: `vault`,
+      `aws-sm`, `gcp-sm`, `azure-kv`, `github-secret`, `1password`,
+      `k8s-secret`, `env`), con su verificación —`evidence: execution`,
+      `expect: success` y `on: entorno`: un comando que demuestra el acceso sin
+      imprimir el valor, como `aws sts get-caller-identity` o `gh secret list`
+      filtrado por nombre— o `verificable: no` con su `motivo`. Cada pendiente
+      del nivel anterior tiene aquí su hijo (en `parents`): si es `antes_de:
+      preparar`, una `respuesta` con `de: <pendiente>` y su `valor`, su
+      `referencia` o su `confirmacion`, según lo que pidió; si es
+      `desplegar:<entorno>`, una `decision` con `antes_de:
+      desplegar:<entorno>`, que queda por decidir y bloquea el hito de ese
+      entorno. UNA RESPUESTA `valor` DE LA QUE DEPENDA EL DESPLIEGUE (la región,
+      el dominio, el nombre del registro) SE RECOGE TAMBIÉN EN UN `tecnico`:
+      la `respuesta` no entra en la entrada del paso de sistema, y el técnico
+      sí. Nunca un secreto: Arketum rechaza lo que tenga su forma. Y el
+      fichero del levantamiento (tipo `documento`, con su `location`).
+    fanout:
+      min: 3
+      max: 80

package/catalogo-de-ejemplo/arquetipos/plan-de-migracion.yaml

@@ -0,0 +1,40 @@
+# Plan de migración.
+#
+# Los movimientos que llevan del sistema actual al nuevo, cada uno con los
+# artefactos que toca. Al aprobarse, fija los tocados de la unidad.
+name: plan-de-migracion
+version: 1.0.0
+description: >-
+  Los movimientos que llevan un sistema existente a su forma nueva, en orden y con los artefactos que toca cada uno. Es el artefacto de trabajo del carril de migración que fija los tocados. Elígelo para planificar una migración; para acotar un cambio sin migrar corresponde el radio de alcance.
+tags: [proceso, migracion, plan]
+
+kinds:
+  - name: objetivo
+    describes: "pieza de la solicitud (L0): de dónde a dónde se migra"
+  - name: movimiento
+    describes: "un paso de la migración; atributo `touches`: los artefactos del proyecto que toca, separados por comas"
+  - name: documento
+    describes: el fichero del plan, en la carpeta de trabajo del paso
+
+extractors:
+  - mechanism: path
+    kind: documento
+    pattern: "<nombre>.md"
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: MIGRACIÓN
+    instruction: >
+      Declara de dónde a dónde se migra y qué no se puede perder (el inventario
+      funcional).
+  - id: L1
+    requiredRoles: []
+    title: MOVIMIENTOS
+    instruction: >
+      Declara los movimientos en orden, cada uno con el atributo `touches` (los
+      artefactos del proyecto que toca, separados por comas), y el fichero del
+      plan (tipo `documento`, con su `location`).
+    fanout:
+      min: 1
+      max: 60

package/catalogo-de-ejemplo/arquetipos/prd.yaml

@@ -0,0 +1,62 @@
+# Documento de requisitos de producto (PRD).
+#
+# Artefacto de trabajo: vive en la carpeta de la unidad y alimenta al paso de
+# sistema. Lo que pide pasa a ser intención de los artefactos tocados cuando
+# declara cómo se comprueba (`projection`); lo demás queda como prosa.
+name: prd
+version: 1.1.0
+description: >-
+  Requisitos de un cambio de producto: qué se pide, para quién y cómo se sabrá que está hecho. Es el artefacto de trabajo con que empiezan los carriles de producto nuevo y de funcionalidad, y alimenta al paso de sistema. Elígelo para pedir algo; para explicar un fallo corresponde un RCA.
+tags: [proceso, requisitos, producto]
+
+kinds:
+  - name: objetivo
+    describes: "pieza de la solicitud (L0): qué se quiere conseguir y para quién"
+  - name: necesidad
+    describes: un problema o una capacidad que pide quien usa el sistema
+  - name: requisito
+    describes: algo concreto que el sistema tiene que hacer o cumplir; con `projection` si se puede comprobar
+  - name: documento
+    describes: el fichero del PRD, en la carpeta de trabajo del paso
+
+extractors:
+  - mechanism: path
+    kind: documento
+    pattern: "<nombre>.md"
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: SOLICITUD
+    instruction: >
+      Declara qué se quiere conseguir, para quién y por qué ahora. Una pieza por
+      objetivo; un objetivo que no se puede dar por cumplido o no no es un objetivo.
+  - id: L1
+    requiredRoles: []
+    title: NECESIDADES
+    instruction: >
+      Declara las necesidades que atiende cada objetivo: el problema de quien usa
+      el sistema, no la solución.
+    fanout:
+      min: 1
+      max: 15
+  - id: L2
+    requiredRoles: []
+    title: REQUISITOS
+    instruction: >
+      Declara los requisitos de cada necesidad y el fichero del PRD (tipo
+      `documento`, con su `location`). Un requisito que se puede comprobar lleva
+      `projection` (relación y argumentos): es el que pasa a ser intención de los
+      artefactos tocados. Uno sin proyección queda como prosa y no se comprueba.
+      Para que entre en el índice de requisitos del artefacto, lleva los
+      atributos `tipo` (`funcional`, `tecnico` o `decision`) y `requisito` (su id
+      corto, estable entre versiones), con `titulo` (hasta 80 caracteres),
+      `sale_de` (la frase de la persona o el requisito del que se deduce),
+      `porque` (obligatorio en un `tecnico`), `aceptacion` y, si la unidad toca
+      varios artefactos, `artefacto`; la versión la pone Arketum. Con el id de
+      uno que ya existe es una versión nueva de ese requisito. Si contradice a un
+      `tecnico` o a una `decision` del mismo artefacto, lo declara con
+      `choca_con` (su id, `<artefacto>:<id>`).
+    fanout:
+      min: 1
+      max: 60

package/catalogo-de-ejemplo/arquetipos/radio-de-alcance.yaml

@@ -0,0 +1,141 @@
+# Radio de alcance de un cambio.
+#
+# Declara la forma de una afirmación que casi nadie escribe y de la que depende
+# todo lo demás: QUÉ PUEDE TOCAR un cambio. No qué tocó — qué puede tocar.
+#
+# Sirve para dos procesos con la misma forma y distinta fuente: en una migración
+# la fuente es el grafo de dependencias; en un requerimiento normativo, la norma.
+#
+# Regla que este arquetipo existe para hacer cumplir: «acotado» no lo declara
+# quien hizo el cambio, y cuando no se puede acotar el radio, el cambio es
+# MASIVO por definición. La frontera se declara con evidencia, igual que lo
+# alcanzado — porque la frontera es la afirmación arriesgada, no la lista.
+name: radio-de-alcance
+version: 1.1.0
+description: >-
+  Análisis de lo que PUEDE tocar un cambio antes de hacerlo: fuentes, alcanzados, fronteras con evidencia y certificaciones. Es un artefacto de trabajo del carril de funcionalidad y de las migraciones. Elígelo para acotar un cambio; para explicar un fallo ya ocurrido corresponde un RCA.
+tags: [proceso, impacto, analisis]
+
+kinds:
+  - name: objetivo
+    describes: "pieza de la solicitud (L0): qué cambio se acota y quién lo declara"
+  - name: fuente
+    describes: de dónde sale el alcance — grafo de dependencias, norma, contrato
+  - name: alcanzado
+    describes: algo que el cambio puede tocar
+  - name: frontera
+    describes: algo que se declara FUERA del radio, con la razón por la que queda fuera
+  - name: evidencia
+    describes: lo que sostiene que algo está dentro o fuera
+  - name: certificacion
+    describes: certificación vigente que cae dentro del radio y hay que reverificar
+  - name: dependencia
+    describes: arista del cableado (L3) entre dos piezas declaradas
+  - name: documento
+    describes: fichero de notas o de política
+
+extractors:
+  - mechanism: path
+    kind: fuente
+    pattern: "fuentes/<nombre>.md"
+  - mechanism: path
+    kind: alcanzado
+    pattern: "alcanzados/<nombre>.md"
+  - mechanism: path
+    kind: frontera
+    pattern: "fronteras/<nombre>.md"
+  - mechanism: path
+    kind: evidencia
+    pattern: "evidencia/<nombre>.md"
+  - mechanism: path
+    kind: certificacion
+    pattern: "certificaciones/<nombre>.md"
+  - mechanism: path
+    kind: documento
+    pattern: "<nombre>.md"
+
+# Lo alcanzado y la frontera pesan igual. Una frontera sin evidencia es la
+# forma en que un radio se declara acotado sin serlo.
+coRequirements:
+  - when: alcanzado
+    requires: [evidencia]
+    scope: artifact
+  - when: frontera
+    requires: [evidencia]
+    scope: artifact
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: CAMBIO
+    instruction: >
+      Declara qué cambió, quién lo hizo, y QUIÉN DECLARA ESTE RADIO — que no
+      puede ser quien hizo el cambio. Declara también contra qué se acota: un
+      grafo de dependencias, una norma, un contrato.
+  - id: L1
+    requiredRoles: [fuentes, frescura]
+    title: FUENTES
+    instruction: >
+      Declara de dónde sale el alcance y CUÁNDO se midió esa fuente. Una fuente
+      con deriva conocida —un índice que se refresca por hora, un grafo cuya cola
+      de fallos crece en silencio— produce un radio corto, y un radio corto
+      produce una recertificación corta que se firma igual. Si no puedes
+      establecer la frescura, dilo aquí: es lo que convierte el radio en masivo.
+    fanout:
+      min: 1
+      max: 10
+  - id: L2
+    requiredRoles: [directos, indirectos, fronteras]
+    title: ALCANCE
+    instruction: >
+      Declara qué puede tocar el cambio: lo que lo usa directamente, lo que llega
+      por transitividad, y lo que queda FUERA. Las tres. Un radio sin fronteras
+      declaradas no está acotado: está sin mirar.
+    fanout:
+      min: 3
+      max: 80
+  - id: L3
+    requiredRoles: []
+    title: CERTIFICACIONES
+    instruction: >
+      Qué certificaciones vigentes caen dentro del radio. Recuerda que una
+      certificación muere por dos causas y solo una deja rastro: cambió el
+      artefacto, o cambió el criterio. La segunda no la dispara ningún commit.
+    fanout:
+      min: 0
+      max: 60
+  - id: L4
+    requiredRoles: []
+    title: RADIO
+    instruction: >
+      Escribe el veredicto: ACOTADO o MASIVO, y qué hay que reverificar. Si es
+      acotado, declara qué se da por bueno sin volver a probar. Si no pudiste
+      acotar, es masivo — y masivo significa todo lo que se intentó, sin muestreo.
+      Declara también el fichero del radio (tipo `documento`, con su `location`):
+      es lo que la fidelidad compara en este último nivel.
+    fanout:
+      min: 1
+      max: 80
+
+selfReview:
+  criteria:
+    - check: Quien declara el radio no es quien hizo el cambio
+      evidence: juicio
+    - check: La fuente del alcance tiene fecha de medición y esa fecha es fresca
+      how: >
+        Nombra la fuente y cuándo se consultó. Si es un índice, comprueba su cola
+        de fallos y su última corrida. Un índice sucio no informa el radio.
+      evidence: medida
+    - check: Cada elemento alcanzado tiene evidencia de por qué está dentro
+      how: Recorre la lista de L2 y contrasta cada uno contra la fuente declarada.
+      evidence: medida
+    - check: Cada frontera tiene evidencia de por qué está fuera
+      how: >
+        Recorre las fronteras y comprueba, contra la misma fuente, que no hay
+        camino desde el cambio. Una frontera sostenida solo en intuición no vale.
+      evidence: medida
+    - check: Si el radio no se pudo acotar, el veredicto dice MASIVO y no acotado
+      evidence: juicio
+  groundingCheck: true
+  groundingScope: alguna fuente, evidencia o certificación
+  assumptionsMustDeclare: true

package/catalogo-de-ejemplo/arquetipos/rca.yaml

@@ -0,0 +1,68 @@
+# Análisis de causa raíz (RCA).
+#
+# Parte de no saber: la señal registra que algo falló, y el RCA investiga hasta
+# confirmar la causa con evidencia. Su último nivel fija qué se toca (atributo
+# `touches`) y cómo se verifica el arreglo (atributos `evidence`, `expect`, `on`).
+name: rca
+version: 1.0.0
+description: >-
+  Investigación de un fallo desde la señal hasta la causa confirmada con evidencia, con lo que hay que tocar y cómo se verifica el arreglo. Es el artefacto de trabajo del carril de corrección: fija los tocados y la verificación. Elígelo para explicar un fallo; para pedir algo nuevo corresponde un PRD.
+tags: [proceso, fallo, causa]
+
+kinds:
+  - name: objetivo
+    describes: "pieza de la solicitud (L0): el fallo tal como se reportó o se detectó"
+  - name: hipotesis
+    describes: una explicación posible del fallo (código, pipeline, entorno o datos)
+  - name: causa
+    describes: la hipótesis confirmada, con la evidencia que la confirma
+  - name: remedio
+    describes: "lo que hay que cambiar; atributo `touches`: los artefactos del proyecto, separados por comas"
+  - name: verificacion
+    describes: "cómo se comprueba el arreglo; atributos `evidence` (clases separadas por comas), `expect` y `on`"
+  - name: documento
+    describes: el fichero del RCA, en la carpeta de trabajo del paso
+
+extractors:
+  - mechanism: path
+    kind: documento
+    pattern: "<nombre>.md"
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: SEÑAL
+    instruction: >
+      Declara el fallo tal como llegó: qué se observó, dónde y quién lo reportó.
+      Todavía no se sabe la causa; no la escribas aquí.
+  - id: L1
+    requiredRoles: []
+    title: HIPÓTESIS
+    instruction: >
+      Declara las hipótesis: en el código, el pipeline, el entorno o los datos.
+      Cada una dice qué se esperaría ver si fuera cierta.
+    fanout:
+      min: 1
+      max: 20
+  - id: L2
+    requiredRoles: []
+    title: CAUSA
+    instruction: >
+      Declara la causa confirmada y con qué evidencia se confirmó. Las hipótesis
+      descartadas se quedan en L1; aquí solo lo que resistió la prueba.
+    fanout:
+      min: 1
+      max: 10
+  - id: L3
+    requiredRoles: []
+    title: REMEDIO Y VERIFICACIÓN
+    instruction: >
+      Declara el remedio (tipo `remedio`, atributo `touches` con los artefactos
+      del proyecto que hay que tocar, separados por comas; ninguno si el fallo no
+      está en el proyecto), la verificación (tipo `verificacion`, atributos
+      `evidence` con las clases que valen, `expect` si admite ejecución y `on`:
+      `before` para una prueba que falla antes del cambio, `change` para la que
+      pasa con él) y el fichero del RCA (tipo `documento`, con su `location`).
+    fanout:
+      min: 1
+      max: 30

package/catalogo-de-ejemplo/arquetipos/servicio-con-integracion.yaml

@@ -0,0 +1,154 @@
+# Servicio que depende de otro sistema. Go.
+#
+# Declara la forma de un servicio con fronteras externas —una pasarela, un
+# sincronizador, un webhook con reintentos—, no la de ninguno. No sabe con qué
+# se integra.
+#
+# La política de este arquetipo es una sola idea: TODA FRONTERA SE DECLARA Y SE
+# PUEDE SUSTITUIR. Lo que no se puede sustituir no se puede probar, y lo que no
+# se puede probar es donde caen los sistemas integrados.
+#
+# Cambios:
+# - 1.1.0: los extractores de código excluyen `<nombre>_test.go` (una prueba
+#   junto a lo que prueba solo la reclama `prueba`); tipos nuevos `modulo`
+#   (go.mod y go.sum) y `arranque` (cmd/<binario>/main.go). La huella cambia:
+#   un proyecto que ya lo usa ve `stale_policy` y recertifica sus artefactos.
+#   `templates/` y `static/` de una web siguen sin tipo.
+name: servicio-con-integracion
+version: 1.1.0
+description: >-
+  Servicio que depende de otros sistemas (pasarela, sincronizador, webhook con reintentos), en Go. Toda frontera externa se declara como puerto y tiene un doble sustituible para probarla. Elígelo cuando lo central del artefacto sea integrarse; para una web con persistencia propia hay otros.
+tags: [codigo, servicio, integracion, go]
+
+kinds:
+  - name: objetivo
+    describes: pieza de la solicitud (L0), sin ubicación en el árbol
+  - name: frontera
+    describes: interfaz que describe un sistema ajeno tal como este lo necesita
+  - name: adaptador
+    describes: implementación de una frontera contra el sistema real
+  - name: doble
+    describes: implementación de una frontera para probar sin el sistema real
+  - name: servicio
+    describes: lógica propia, que no habla con nadie de fuera
+  - name: dependencia
+    describes: arista del cableado (L3) entre dos piezas declaradas
+  - name: prueba
+    describes: fichero de prueba
+  - name: modulo
+    describes: la definición del módulo de Go y sus sumas (go.mod, go.sum)
+  - name: arranque
+    describes: el punto de entrada de un binario (cmd/<binario>/main.go)
+  - name: documento
+    describes: fichero de documentación o de política
+
+# Una prueba vive junto a lo que prueba (`x_test.go`): cada extractor de código
+# la excluye, para que solo la reclame `prueba`.
+extractors:
+  - mechanism: path
+    kind: frontera
+    pattern: "internal/fronteras/<nombre>.go"
+    excluding: ["internal/fronteras/<nombre>_test.go"]
+  - mechanism: path
+    kind: adaptador
+    pattern: "internal/adaptadores/<nombre>.go"
+    excluding: ["internal/adaptadores/<nombre>_test.go"]
+  - mechanism: path
+    kind: doble
+    pattern: "internal/dobles/<nombre>.go"
+    excluding: ["internal/dobles/<nombre>_test.go"]
+  - mechanism: path
+    kind: servicio
+    pattern: "internal/servicios/<nombre>.go"
+    excluding: ["internal/servicios/<nombre>_test.go"]
+  - mechanism: path
+    kind: prueba
+    pattern: "internal/<paquete>/<nombre>_test.go"
+  # go.mod y go.sum: un extractor por tipo, y el marcador casa con media palabra.
+  - mechanism: path
+    kind: modulo
+    pattern: "go.<fichero>"
+  - mechanism: path
+    kind: arranque
+    pattern: "cmd/<binario>/main.go"
+
+# Un adaptador sin doble es una frontera que solo se puede ejercitar contra el
+# sistema real: la prueba se vuelve lenta, frágil y acaba desactivada.
+coRequirements:
+  - when: adaptador
+    requires: [doble]
+    scope: artifact
+  - when: servicio
+    requires: [prueba]
+    scope: artifact
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: SOLICITUD
+    instruction: >
+      Declara qué tiene que conseguir el servicio y con qué sistemas ajenos
+      necesita hablar para conseguirlo. Nombra los sistemas; no cómo se les
+      llama por dentro.
+  - id: L1
+    requiredRoles: [fronteras, adaptadores, servicios]
+    title: PARTES
+    instruction: >
+      Propón las partes, separando lo que es tuyo de lo que es de otro. Una
+      pieza que mezcle lógica propia con una llamada a un sistema ajeno no
+      podrá probarse sin ese sistema, y este nivel existe para impedirlo.
+    fanout:
+      min: 3
+      max: 14
+  - id: L2
+    requiredRoles: []
+    title: CONTRATOS
+    instruction: >
+      Declara cada frontera tal como TU servicio la necesita, no como la
+      documenta el proveedor. Y declara qué pasa cuando el sistema ajeno falla,
+      tarda o responde algo que no esperabas: eso también es el contrato.
+    fanout:
+      min: 1
+      max: 30
+  - id: L3
+    requiredRoles: []
+    title: CABLEADO
+    instruction: >
+      Declara qué depende de qué, y en particular qué pieza depende de qué
+      frontera. Ninguna pieza de lógica propia debería depender de un adaptador:
+      si lo hace, la frontera no está haciendo su trabajo.
+    fanout:
+      min: 1
+      max: 40
+  - id: L4
+    requiredRoles: []
+    title: IMPLEMENTACIÓN
+    instruction: >
+      Escribe el código. Cada adaptador viene con su doble, y la lógica propia
+      se prueba sin levantar nada de fuera.
+    fanout:
+      min: 1
+      max: 70
+
+# La autorrevisión: qué comprobar del servicio entregado, y con qué acción.
+selfReview:
+  criteria:
+    - check: La cobertura de pruebas unitarias del código propio es al menos del 80%
+      how: Corre la suite con reporte de cobertura y lee el total de líneas.
+      evidence: medida
+    - check: No hay hallazgos de OWASP Top 10 en lo entregado
+      how: >
+        Revisa entrada sin validar, autenticación y control de acceso, secretos
+        en el árbol, y qué se registra de lo que llega de fuera.
+      evidence: medida
+    - check: Ninguna pieza de lógica propia depende de un adaptador
+      how: Sigue las dependencias declaradas en L3 desde cada servicio.
+      evidence: medida
+    - check: Cada frontera declarada en L2 tiene doble, y el doble cubre el fallo y la demora
+      how: Contrasta la lista de fronteras contra la de dobles, y lee cada doble.
+      evidence: medida
+    - check: Lo implementado cumple la intención declarada en L0, y no una parecida
+      evidence: juicio
+  groundingCheck: true
+  groundingScope: alguna api, módulo, clase, función o dato
+  assumptionsMustDeclare: true

package/catalogo-de-ejemplo/carriles/ajuste.yaml

@@ -0,0 +1,14 @@
+# Un ajuste: un cambio chico sobre piezas que ya existen (la 35). Se piensa por
+# cambio (la cita literal del pedido y un radio corto) y se prueba en grupo: cierra
+# sin las condiciones 9 y 10, que juzga una `comprobacion` de los ajustes sin
+# comprobar. Su tamaño lo mide Arketum contra la línea base: si se excede, se
+# descarta y se continúa en `funcionalidad` (`continua`), con su foto.
+name: ajuste
+version: 1.0.0
+when: Un cambio chico sobre piezas que ya existen. Si resulta más grande, Arketum lo dice y sube a `funcionalidad`.
+comprobacion: agrupada
+tope_sin_comprobar: 5
+max_cambios_sin_comprobar: 16
+steps:
+  - { id: ajuste, kind: artifact, archetype: { name: ajuste }, gate: true, levantamiento: breve, max_requisitos: 3, feeds: [sistema] }
+  - { id: sistema, kind: system, fedBy: [ajuste], max_cambios: 8, piezas: L1 }

package/catalogo-de-ejemplo/carriles/arquetipo.yaml

@@ -0,0 +1,13 @@
+# Un arquetipo nuevo: se escribe y se publica en el catálogo que elija la
+# persona.
+name: arquetipo
+version: 1.0.0
+when: Ningún arquetipo de los catálogos describe un tipo de artefacto que se va a construir.
+milestones: [entrega]
+steps:
+  - { id: arquetipo, kind: artifact, archetype: { name: arquetipo-autor }, gate: true }
+  - id: hito
+    kind: milestone
+    gate: true
+    requires:
+      - { id: publicado, describes: la persona confirma que el arquetipo está publicado en el catálogo que eligió, classes: [statement] }

package/catalogo-de-ejemplo/carriles/comprobacion.yaml

@@ -0,0 +1,23 @@
+# La comprobación agrupada (la 35): comprueba juntos los ajustes sin comprobar.
+# Recertifica cada tocado contra el árbol de ahora (con descenso heredado; los
+# arreglos van aquí, con el mismo tope que un ajuste) y exige las salidas: el
+# suelo, la suite e2e entera y la e2e de cada funcional de los ajustes.
+name: comprobacion
+version: 1.0.0
+when: Comprobar juntos los ajustes sin comprobar, antes de desplegar o cuando se acumulan.
+comprueba: true
+milestones: [despliegue, entrega, ejecucion]
+steps:
+  - { id: sistema, kind: system, max_cambios: 8, piezas: L1 }
+  - id: comprobacion
+    salidas: true
+    kind: evidence
+    requires:
+      - { id: no-regresion, describes: lo que ya funcionaba sigue funcionando, classes: [execution], expect: success }
+  - id: hito
+    kind: milestone
+    optional: true
+    gate: true
+    confirmacion: true
+    requires:
+      - { id: cumplido, describes: la persona confirma que el hito se cumplió, classes: [statement] }

package/catalogo-de-ejemplo/carriles/correccion.yaml

@@ -0,0 +1,25 @@
+# Una corrección parte de no saber: la señal registra el fallo, el RCA
+# investiga y fija qué se toca y cómo se verifica.
+#
+# Cambios:
+# - 1.1.0: el hito `despliegue <entorno>` cuenta (`humo: true`): exige la prueba de humo y que el entorno exista.
+# - 1.2.0: el hito `despliegue <entorno>` lo cumple la confirmación de la persona por el canal interactivo («¿se desplegó en <entorno> y corrió?», sí o no): la marca `humo` pasa a llamarse `confirmacion` y la prueba de humo deja de exigirse.
+name: correccion
+version: 1.2.0
+when: Un fallo reportado o detectado, del que todavía no se sabe la causa.
+milestones: [despliegue, entrega, ejecucion]
+steps:
+  - id: senal
+    kind: evidence
+    requires:
+      - { id: fallo, describes: el fallo tal como llegó, classes: [execution, report, statement], expect: failure, on: before }
+  - { id: rca, kind: artifact, archetype: { name: rca }, gate: true, fixesTouches: true, feeds: [sistema, verificacion] }
+  - { id: sistema, kind: system, optional: true, fedBy: [rca] }
+  - { id: verificacion, kind: evidence, fedBy: [rca] }
+  - id: hito
+    kind: milestone
+    optional: true
+    gate: true
+    confirmacion: true
+    requires:
+      - { id: cumplido, describes: la persona confirma que el hito se cumplió, classes: [statement] }