@rlabs-cl/arketum 0.0.0-stage → 1.0.1

package/catalogo-de-ejemplo/agentes.yaml

@@ -0,0 +1,11 @@
+# Los nombres de los clientes que Arketum lee o escribe por función (ag-t01): el código de src/ no los escribe.
+# En varios catálogos, cada lista es la unión de las suyas, en orden.
+#
+# - instrucciones: los ficheros de instrucciones que se generan para los agentes, en la raíz del proyecto, con el
+#   mismo texto (`action: instructions`); el estado avisa si el que hay ya no es el que se generaría.
+# - configuracion: las carpetas de configuración de editores y agentes que la herramienta crea solo por abrir la
+#   carpeta: en la raíz, no cuentan para clasificar el arranque y se proponen como andamiaje.
+# - andamiaje: el andamiaje mínimo que propone el arranque, además de los ficheros de instrucciones.
+instrucciones: [AGENTS.md, CLAUDE.md]
+configuracion: [.claude/, .vscode/, .idea/, .cursor/]
+andamiaje: [.git/, node_modules/, dist/]

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

@@ -0,0 +1,54 @@
+# Un ajuste: un cambio chico sobre piezas que ya existen (la 35).
+#
+# Artefacto de trabajo del carril `ajuste`: vive en la carpeta de la unidad y
+# alimenta al paso de sistema. Su primer nivel es el radio corto (qué pieza toca
+# y qué más podría tocar); el último, los requisitos, con su cita literal del
+# pedido de la persona.
+name: ajuste
+version: 1.0.0
+description: >-
+  Un cambio chico sobre piezas que ya existen: qué pieza toca, qué más podría tocar y cómo se notaría, y los requisitos con su cita del pedido de la persona. Es el artefacto de trabajo del carril `ajuste`; para algo nuevo o grande corresponde un PRD.
+tags: [proceso, requisitos, ajuste]
+
+kinds:
+  - name: toca
+    describes: "una pieza de un tocado que el cambio toca: `artefacto` (uno de los tocados) y `pieza` (el id de un elemento del nivel de piezas de su línea base)"
+  - name: riesgo
+    describes: lo que más podría tocar el cambio y cómo se notaría en la comprobación; si no hay, uno solo con id `ninguno` y su `porque`
+  - name: requisito
+    describes: algo concreto que el sistema tiene que hacer o cumplir, con su cita del pedido
+  - name: documento
+    describes: el fichero del ajuste, en la carpeta de trabajo del paso
+
+extractors:
+  - mechanism: path
+    kind: documento
+    pattern: "<nombre>.md"
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: RADIO
+    instruction: >
+      Declara qué pieza toca el cambio, una `toca` por pieza, con `artefacto` (uno
+      de los tocados; cada tocado, al menos una) y `pieza` (el id de un elemento
+      del nivel de piezas de su último descenso certificado, el que se va a
+      heredar). Y pregúntate qué más toca esto: un `riesgo` por cada cosa que
+      podría romperse, con cómo se notaría en la comprobación (por ejemplo, que
+      las corridas guardadas se reproduzcan igual). Si de verdad no hay ninguno,
+      un solo `riesgo` con id `ninguno` y su `porque`.
+  - id: L1
+    requiredRoles: []
+    title: REQUISITOS
+    instruction: >
+      Declara los requisitos del ajuste y el fichero del ajuste (tipo
+      `documento`, con su `location`). Cada requisito lleva los atributos `tipo`
+      (`funcional` o `tecnico`), `requisito` (su id corto; con el de uno que ya
+      existe es una versión nueva), `titulo`, `sale_de` (la frase literal del
+      pedido de la persona, o de su respuesta a una pregunta), `porque` en un
+      `tecnico`, `aceptacion` y, si la unidad toca varios artefactos,
+      `artefacto`. Pocos: si hacen falta más de los que admite el carril, no es
+      un ajuste.
+    fanout:
+      min: 1
+      max: 10

package/catalogo-de-ejemplo/arquetipos/arquetipo-autor.yaml

@@ -0,0 +1,72 @@
+# Autoría de un arquetipo.
+#
+# El arquetipo que se escribe es un fichero YAML de la carpeta de trabajo; el
+# descenso llega hasta él. Al aprobarse el paso, Arketum lo publica en el
+# catálogo que elige la persona; el hito del carril `arquetipo` lo confirma.
+#
+# Cambios:
+# - 1.3.0: crea también formas de sistema (tipo `forma_de_sistema`, en `formas/`), cuando el levantamiento eligió una nueva.
+# - 1.2.0: varios candidatos en un mismo paso (los que agrega la arquitectura).
+# - 1.1.0: también un stack (`stacks/<nombre>.yaml` de la carpeta de trabajo),
+#   que se publica en `stacks/` del catálogo elegido.
+name: arquetipo-autor
+version: 1.3.0
+description: >-
+  Escritura de un arquetipo nuevo: para qué tipo de artefacto, con qué tipos de elemento, extractores y niveles, hasta el fichero YAML que lo declara. Es el artefacto de trabajo del carril de arquetipo y, opcional, de los de producto nuevo y funcionalidad. Elígelo cuando ningún arquetipo de los catálogos describe lo que se va a construir.
+tags: [proceso, arquetipo, politica]
+
+kinds:
+  - name: objetivo
+    describes: "pieza de la solicitud (L0): qué tipo de artefacto describe el arquetipo"
+  - name: forma
+    describes: un tipo de elemento, un extractor o un nivel de la escalera que el arquetipo declara
+  - name: arquetipo
+    describes: el fichero YAML del arquetipo, en la carpeta de trabajo del paso
+  - name: stack
+    describes: "el fichero YAML de un stack (con qué se construye), en `stacks/` de la carpeta de trabajo del paso"
+  - name: forma_de_sistema
+    describes: "el fichero YAML de una forma de sistema (señales, `aplica`, diseño, huecos, variantes y escalones), en `formas/` de la carpeta de trabajo del paso"
+
+extractors:
+  - mechanism: path
+    kind: arquetipo
+    pattern: "<nombre>.yaml"
+  - mechanism: path
+    kind: stack
+    pattern: "stacks/<nombre>.yaml"
+  - mechanism: path
+    kind: forma_de_sistema
+    pattern: "formas/<nombre>.yaml"
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: SOLICITUD
+    instruction: >
+      Declara qué tipo de artefacto describirá el arquetipo y por qué ninguno de
+      los catálogos sirve.
+  - id: L1
+    requiredRoles: []
+    title: FORMA
+    instruction: >
+      Declara la forma: tipos de elemento, cómo se reconoce cada uno en el árbol
+      (extractores) y los niveles de la escalera con su instrucción.
+    fanout:
+      min: 1
+      max: 40
+  - id: L2
+    requiredRoles: []
+    title: ARQUETIPO
+    instruction: >
+      Declara el fichero del arquetipo (tipo `arquetipo`, con `location` a un
+      YAML de la carpeta de trabajo) o el de un stack (tipo `stack`, con
+      `location` a `stacks/<name>.yaml`). Tiene que cargar, su `name` es un slug
+      y el fichero se llama `<name>.yaml`. Si la arquitectura agrega varios,
+      uno por cada uno. Si el levantamiento eligió una forma de sistema nueva
+      («no_calza»), declara también su fichero (tipo `forma_de_sistema`, con
+      `location` a `formas/<name>.yaml`), con señales que su `aplica` cumple,
+      y, si sus variantes piden suelo o e2e, un stack con las fijaciones de
+      esa forma.
+    fanout:
+      min: 1
+      max: 20

package/catalogo-de-ejemplo/arquetipos/arquitectura-de-sistema.yaml

@@ -0,0 +1,72 @@
+# Arquitectura del sistema.
+#
+# Su último nivel es una propuesta de proyecto: los artefactos con su raíz, su
+# arquetipo, sus dependencias y lo que se toca con ellos; el andamiaje; y la
+# cobertura. Al aprobarse, fija los tocados (elementos de tipo `artefacto`).
+#
+# Cambios:
+# - 1.1.0: un artefacto declara su arquetipo de una sola capa (`archetype`) o,
+#   con capas, `stack` (con qué se construye) y `componente` (de la variante de
+#   la forma del proyecto); Arketum compone el arquetipo efectivo.
+# - 1.2.0: cada artefacto lleva su juicio de ajuste (`ajuste`, `por_que` y, si
+#   nada calza, `nuevo`): se entrega la mejor alternativa para el caso de uso, no
+#   la que hay a mano (convención `ajuste: obligatorio`).
+name: arquitectura-de-sistema
+version: 1.2.0
+description: >-
+  Propuesta de cómo se parte un sistema en artefactos: raíz, arquetipo, dependencias y `touchWith` de cada uno, el andamiaje y la cobertura. Es el artefacto de trabajo de un producto nuevo y, opcional, de una funcionalidad que añade artefactos. Elígelo para decidir la forma del proyecto, no la de un artefacto.
+tags: [proceso, arquitectura, proyecto]
+
+kinds:
+  - name: objetivo
+    describes: "pieza de la solicitud (L0): qué sistema se quiere y con qué restricciones"
+  - name: componente
+    describes: una responsabilidad del sistema, antes de decidir en qué artefacto vive
+  - name: artefacto
+    describes: "un artefacto del proyecto; id = el del artefacto; atributos `root`, `archetype` (nombre o nombre@versión) o, con capas, `stack` (nombre o nombre@versión) y `componente` (de la variante de la forma del proyecto), `dependsOn` y `touchWith` (ids separados por comas); y el juicio de ajuste: `ajuste` («calza», «calza_con_reservas» o «no_calza»), `por_que` (los elementos del caso de uso que inclinan a esta elección; con reservas, cuáles) y, con «no_calza», `nuevo` (por qué ninguno de los que hay calza y qué tendría el que se agrega)"
+  - name: andamiaje
+    describes: "algo que ningún arquetipo gobierna; atributo `path` (acabado en / para una carpeta)"
+  - name: cobertura
+    describes: "la cobertura del proyecto; atributo `value`: aviso o bloquea"
+  - name: documento
+    describes: el fichero de la arquitectura o un diagrama, en la carpeta de trabajo del paso
+
+extractors:
+  - mechanism: path
+    kind: documento
+    pattern: "<nombre>.md"
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: SOLICITUD
+    instruction: >
+      Declara qué sistema se quiere, para qué y con qué restricciones (equipo,
+      plataforma, plazos).
+  - id: L1
+    requiredRoles: []
+    title: COMPONENTES
+    instruction: >
+      Declara las responsabilidades del sistema y cómo se relacionan, antes de
+      decidir cuántos artefactos hay.
+    fanout:
+      min: 1
+      max: 30
+  - id: L2
+    requiredRoles: []
+    title: PROYECTO
+    instruction: >
+      Declara la propuesta de proyecto: un elemento `artefacto` por artefacto (su
+      id es el del artefacto; atributos `root`, `archetype` —o, con capas,
+      `stack` y `componente`—, `dependsOn` y `touchWith`), un elemento
+      `andamiaje` por ruta que ningún arquetipo
+      gobierna (atributo `path`), un elemento `cobertura` (atributo `value`) y
+      el fichero de la arquitectura (tipo `documento`, con su `location`).
+      Cada `artefacto` lleva su juicio de ajuste: si lo elegido calza con el caso de uso (`ajuste`: calza, calza_con_reservas o no_calza), los elementos del caso que inclinan a esa elección (`por_que`) y, si nada de lo que hay en los catálogos calza, `nuevo`: por qué ninguno calza y qué tendría el que se agrega, con un nombre propio que no exista. Elige la mejor alternativa para el caso de uso, no la que está a mano: crear uno nuevo siempre es una alternativa; si se agrega, Arketum incluye el paso que lo crea y la persona lo aprueba allí.
+    fanout:
+      min: 1
+      max: 60
+
+# El juicio de ajuste de cada artefacto de la propuesta lo exige Arketum al entregar el último nivel.
+conventions:
+  ajuste: obligatorio

package/catalogo-de-ejemplo/arquetipos/despliegue-compose.yaml

@@ -0,0 +1,104 @@
+# Despliegue con Docker Compose.
+#
+# Artefacto del sistema de una sola capa: la definición del despliegue, la
+# configuración de cada entorno (de ejemplo, nunca la real), su documentación y,
+# si se quiere, una prueba de humo (`humo.sh`, ubicación sugerida, no exigida).
+#
+# Cambios:
+# - 1.1.0: `verificacion` (`humo.sh`) deja de ser obligatoria: el hito `despliegue <entorno>` lo cumple la
+#   confirmación de la persona, y Arketum no exige una forma concreta de comprobar el despliegue. Su raíz es `despliegue/`, para no solaparse con una raíz
+# `.`: el compose se invoca como `docker compose -f despliegue/compose.yaml`.
+# Los demás modos (pipeline, script…) se publican por el paso `arquetipo`.
+name: despliegue-compose
+version: 1.1.0
+description: >-
+  Despliegue de un sistema con Docker Compose: la definición (`compose.yaml`), la configuración de ejemplo de cada entorno (`<entorno>.env.example`, nunca `.env`), su documentación (`DESPLIEGUE.md`) y, si se quiere, una prueba de humo (`humo.sh`), en la raíz `despliegue/`. Elígelo cuando el levantamiento de infraestructura acuerde el modo `compose`.
+tags: [despliegue, infraestructura, compose]
+# Gobierna un artefacto de despliegue: el carril `despliegue` exige uno así entre los tocados. Un arquetipo propio de
+# otro modo (pipeline, script…) lo declara igual.
+despliegue: true
+
+kinds:
+  - name: objetivo
+    describes: "pieza de la solicitud (L0): lo que se despliega y en qué entorno, de los técnicos del levantamiento"
+  - name: definicion
+    describes: la definición del despliegue (`compose.yaml`, o `compose.<entorno>.yaml` si un entorno la cambia)
+  - name: entorno
+    describes: "la configuración de ejemplo de un entorno (`<entorno>.env.example`): variables con marcadores, nunca valores secretos"
+  - name: verificacion
+    describes: "opcional: la prueba de humo (`humo.sh`), que comprueba contra lo desplegado que funciona, sin imprimir secretos"
+  - name: documentacion
+    describes: cómo se despliega, se verifica y se revierte cada entorno (`DESPLIEGUE.md`)
+
+extractors:
+  - mechanism: path
+    kind: definicion
+    pattern: "compose.yaml"
+    alternatives: ["compose.<entorno>.yaml"]
+  - mechanism: path
+    kind: entorno
+    pattern: "<entorno>.env.example"
+  - mechanism: path
+    kind: verificacion
+    pattern: "humo.sh"
+  - mechanism: path
+    kind: documentacion
+    pattern: "DESPLIEGUE.md"
+
+# Una definición sin documentación no la sabe operar nadie más. La prueba de humo
+# no se exige: si corrió lo confirma la persona en el hito.
+coRequirements:
+  - when: definicion
+    requires: [documentacion]
+    scope: artifact
+
+conventions:
+  oficio.1: >-
+    Los secretos no van en el repositorio: un `.env` dentro de `despliegue/` queda sin reclamar y no cierra la unidad.
+    Sácalo del repositorio, declara en su lugar su referencia (`<esquema>:<ruta>`) en el levantamiento de
+    infraestructura y deja en `<entorno>.env.example` la variable con un marcador (`DB_PASSWORD=<desde vault:kv/app/db>`).
+  oficio.2: >-
+    La validación en seco es `docker compose -f despliegue/compose.yaml config --quiet`, desde la raíz del proyecto;
+    la exige el paso `preparado` como una ejecución `on: change` con código 0. No necesita el daemon de Docker (solo
+    lee y valida la definición): se ejecuta de verdad aunque no se pueda levantar nada.
+  oficio.3: >-
+    `humo.sh`, si lo hay, comprueba lo desplegado por el camino real (una petición HTTP, una orden del programa) y
+    termina con 0 si funciona; recibe el entorno como argumento y no imprime ningún secreto. Es una ayuda, no una
+    exigencia: el hito `despliegue <entorno>` lo cumple la persona al confirmar que se desplegó y corrió; su ejecución
+    `on: entorno` (o el reporte del CI) se entrega como respaldo y sale en la pregunta.
+  oficio.4: >-
+    `DESPLIEGUE.md` dice, por entorno, cómo se despliega, cómo se comprueba que corrió (con `humo.sh` si lo hay), cómo se revierte y de dónde salen
+    las variables de cada `<entorno>.env.example`.
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: OBJETIVO
+    instruction: >
+      Declara qué se despliega y en qué entornos, atendiendo a los técnicos del
+      levantamiento de infraestructura (la entrada): el modo, cada entorno y lo
+      acordado de cada uno.
+  - id: L1
+    requiredRoles: []
+    title: PIEZAS
+    instruction: >
+      Propón las piezas: la definición, la configuración de ejemplo de cada
+      entorno (nunca la real: los secretos van por su referencia), la
+      documentación y, si ayuda, la prueba de humo. Un `.env` no es una pieza: queda fuera del
+      repositorio.
+    fanout:
+      min: 3
+      max: 20
+  - id: L2
+    requiredRoles: []
+    title: FICHEROS
+    instruction: >
+      Declara cada fichero con su `location`, relativa a `despliegue/`:
+      `compose.yaml`, `<entorno>.env.example`, `DESPLIEGUE.md` y, si lo hay,
+      `humo.sh`. Si
+      dentro de `despliegue/` hay un `.env`, sácalo del repositorio y declara su
+      referencia en el levantamiento de infraestructura: aquí no lo reclama
+      nadie, y una unidad con un fichero sin reclamar no cierra.
+    fanout:
+      min: 3
+      max: 30

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

@@ -0,0 +1,97 @@
+# Digestión de un código que ya existe.
+#
+# Su último nivel es la estructura base del proyecto: los artefactos (con su
+# stack y su componente, o su arquetipo), la forma con sus señales (cada una con
+# las rutas del árbol que la sostienen), el andamiaje y la cobertura. Arketum
+# añade en la guía de cada nivel lo que calcula del árbol: las raíces candidatas
+# (por las ubicaciones de raíz de los stacks), el encaje de cada stack y lo que
+# queda fuera. La variante y los escalones los deriva Arketum de las señales.
+#
+# Cambios:
+# - 1.1.0: cada artefacto lleva su juicio de ajuste (`ajuste`, `por_que` y, si
+#   nada calza, `nuevo`), como en la arquitectura (convención `ajuste: obligatorio`).
+# - 1.2.0: la forma también lleva su juicio de ajuste (`ajuste` y `por_que`); una
+#   digestión no crea formas: si ninguna calza, se crea antes con el carril de
+#   arquetipo, o se digiere con reservas (convención `ajuste_forma: obligatorio`).
+# - 1.3.0: forzar una forma que no cumple su `aplica` lo elige la persona: su
+#   respuesta, en el atributo `eleccion` de la `forma`.
+name: digestion
+version: 1.3.0
+description: >-
+  Digestión de un código que ya existe: de lo que hay en el árbol a la estructura base de Arketum (artefactos, forma con sus señales, andamiaje y cobertura), sin cambiar código ni inferir requisitos. Es el artefacto de trabajo del carril `digestion`.
+tags: [proceso, digestion, proyecto]
+
+kinds:
+  - name: raiz
+    describes: "una raíz candidata del árbol (L0); atributo `path`"
+  - name: fuera
+    describes: "un grupo de rutas que no cae en ninguna raíz candidata (L0); atributo `path`"
+  - name: decision
+    describes: "qué es una raíz o un grupo (L1): un artefacto con capas (`stack` y `componente`), uno de una sola capa (`archetype`) o andamiaje"
+  - name: artefacto
+    describes: "un artefacto del proyecto (L2); id = el del artefacto; atributos `root`, `archetype` (nombre o nombre@versión) o, con capas, `stack` y `componente`, `dependsOn` y `touchWith` (ids separados por comas); y el juicio de ajuste: `ajuste` («calza», «calza_con_reservas» o «no_calza»), `por_que` (los elementos del caso de uso que inclinan a esta elección; con reservas, cuáles) y, con «no_calza», `nuevo` (por qué ninguno de los que hay calza y qué tendría el que se agrega)"
+  - name: andamiaje
+    describes: "algo que ningún arquetipo gobierna (L2); atributo `path` (acabado en / para una carpeta)"
+  - name: cobertura
+    describes: "la cobertura del proyecto (L2); atributo `value`: aviso o bloquea"
+  - name: forma
+    describes: "la forma de sistema (L2); atributo `name`, su juicio de ajuste (`ajuste`: «calza», que cumple su `aplica`, o «calza_con_reservas», con lo que se fuerza; y `por_que`, lo que en el árbol inclina a ella) y, si no cumple su `aplica` sin reservas, `motivo`; si no cumple su `aplica`, `eleccion`: lo que respondió la persona a forzarla o crear una nueva; la variante y los escalones los deriva Arketum (si los declaras, `variante` y `escalones`, tienen que casar; si ninguna variante aplica, `motivo_variante`)"
+  - name: senal
+    describes: "una señal de la forma (L2); id = la señal; atributos `valor` (con su tipo), `porque` y `rutas` (rutas del árbol que la sostienen, separadas por comas)"
+  - name: retirar
+    describes: "en un proyecto con artefactos, uno que sale de `proyecto.yaml` (L2); id = el artefacto (sin raíz, sin unidad viva y sin requisitos vivos)"
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: RAÍCES
+    instruction: >
+      Lee el árbol (rutas, no contenidos) y lo que Arketum calcula de él en esta
+      guía. Declara un elemento `raiz` por cada raíz que vayas a proponer
+      (atributo `path`; `.` es la raíz del proyecto) y un elemento `fuera` por
+      cada grupo de rutas que no cae en ninguna (atributo `path`).
+    fanout:
+      min: 1
+      max: 40
+  - id: L1
+    requiredRoles: []
+    title: STACKS
+    instruction: >
+      Por cada raíz y cada grupo de fuera, un elemento `decision` (con su padre
+      en L0): con capas, `stack` y `componente` (el stack con más encaje no es
+      obligatorio, pero lo que dejas sin reclamar sale en el gate); de una sola
+      capa, `archetype`; o `andamiaje`. Lee del código lo justo para decidir la
+      forma del sistema: cuántos despliegues, pantallas, actores e integraciones,
+      y qué rutas lo muestran.
+    fanout:
+      min: 1
+      max: 40
+  - id: L2
+    requiredRoles: []
+    title: ESTRUCTURA BASE
+    instruction: >
+      Declara la estructura base, cada elemento con su padre en L1: un
+      `artefacto` por artefacto (atributos `root` y `stack` y `componente`, o
+      `archetype`; `dependsOn` y `touchWith` si hacen falta), un `andamiaje` por
+      ruta que no gobierna nadie (atributo `path`), una `cobertura` (`aviso` sobre
+      un código que ya existe), la `forma` (atributo `name`) y una `senal` por
+      cada señal de la forma, con `valor`, `porque` y `rutas` (las rutas del árbol
+      que la sostienen). Lo que dejes fuera de toda raíz y del andamiaje no se
+      rechaza: sale en el gate como lo que queda fuera (será deriva
+      `fuera_de_raiz`), y la persona decide caso a caso.
+      La variante y los escalones los deriva Arketum de las señales. En un
+      proyecto con artefactos, `retirar` los que ya no tienen raíz. No declares
+      requisitos: sembrarlos es otra unidad.
+      La `forma` lleva también su juicio de ajuste (`ajuste` y `por_que`): una digestión no crea formas; si ninguna calza, se crea antes con el carril de arquetipo, o se digiere con reservas. Si la más cercana no cumple su `aplica`, forzarla lo elige la persona, no tú: Arketum te da la pregunta, y su respuesta va en el atributo `eleccion` de la `forma`.
+      Cada `artefacto` lleva su juicio de ajuste: si lo elegido calza con el caso de uso (`ajuste`: calza, calza_con_reservas o no_calza), los elementos del caso que inclinan a esa elección (`por_que`) y, si nada de lo que hay en los catálogos calza, `nuevo`: por qué ninguno calza y qué tendría el que se agrega, con un nombre propio que no exista. Elige la mejor alternativa para el caso de uso, no la que está a mano: crear uno nuevo siempre es una alternativa; si se agrega, Arketum incluye el paso que lo crea y la persona lo aprueba allí.
+    # Un elemento por artefacto y por andamiaje, la cobertura, la forma, sus
+    # señales (hasta siete en el catálogo de ejemplo) y lo que se retira: 120
+    # deja sitio a un monorepo de unas cien piezas sin partir la digestión.
+    fanout:
+      min: 1
+      max: 120
+
+# El juicio de ajuste de cada artefacto de la estructura base lo exige Arketum al entregar el último nivel.
+conventions:
+  ajuste: obligatorio
+  ajuste_forma: obligatorio

package/catalogo-de-ejemplo/arquetipos/documento-academico.yaml

@@ -0,0 +1,131 @@
+# Documento académico. LaTeX.
+#
+# Declara la forma de un documento que sostiene afirmaciones —una tesis, un
+# artículo, un informe de investigación—, no el contenido de ninguno. No sabe
+# de qué trata.
+#
+# Este arquetipo existe además para probar algo: si la escalera solo sirviera
+# para código, aquí se rompería.
+name: documento-academico
+version: 1.0.0
+description: >-
+  Documento que sostiene afirmaciones con fuentes (tesis, artículo, informe de investigación), en LaTeX. Desciende de la pregunta a la estructura, las afirmaciones y sus dependencias, hasta el manuscrito. Elígelo cuando el artefacto sea prosa que tiene que poder defenderse, no documentación de un sistema.
+tags: [documento, investigacion, latex]
+
+kinds:
+  - name: objetivo
+    describes: "pieza de la solicitud (L0): qué se quiere demostrar"
+  - name: capitulo
+    describes: sección mayor con una tesis propia
+  - name: afirmacion
+    describes: lo que un capítulo sostiene y que puede ser falso
+  - name: figura
+    describes: imagen, diagrama o gráfico
+  - name: pie
+    describes: texto que explica una figura y la hace citable
+  - name: referencia
+    describes: entrada bibliográfica
+  - name: dato
+    describes: fichero de datos que respalda una afirmación
+  - name: dependencia
+    describes: arista del cableado (L3) entre dos piezas declaradas
+  - name: documento
+    describes: fichero de política o de notas
+
+extractors:
+  - mechanism: path
+    kind: capitulo
+    pattern: "capitulos/<nombre>.tex"
+  - mechanism: path
+    kind: figura
+    pattern: "figuras/<nombre>.pdf"
+  - mechanism: path
+    kind: pie
+    pattern: "figuras/<nombre>.tex"
+  - mechanism: path
+    kind: referencia
+    pattern: "bibliografia/<nombre>.bib"
+  - mechanism: path
+    kind: dato
+    pattern: "datos/<nombre>.csv"
+
+# Una figura sin pie no se puede citar ni entender fuera de su página. Es el
+# mismo co-requisito que «implementación necesita prueba», en otro dominio.
+coRequirements:
+  - when: figura
+    requires: [pie]
+    scope: artifact
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: PREGUNTA
+    instruction: >
+      Declara qué se quiere demostrar y ante quién. Una pregunta que no puede
+      responderse «no» no es una pregunta de investigación.
+  - id: L1
+    requiredRoles: [introduccion, desarrollo, conclusion]
+    title: ESTRUCTURA
+    instruction: >
+      Propón la estructura de capítulos y qué cubre cada uno. Todo documento que
+      sostiene algo plantea, desarrolla y concluye; si tu estructura no distingue
+      esas tres funciones, no está estructurada.
+    fanout:
+      min: 3
+      max: 15
+  - id: L2
+    requiredRoles: []
+    title: AFIRMACIONES
+    instruction: >
+      Declara qué afirma cada capítulo y con qué evidencia lo sostiene. Una
+      afirmación que ninguna evidencia puede desmentir no es una afirmación:
+      decláralo si es el caso, en vez de disfrazarla.
+    fanout:
+      min: 1
+      max: 40
+  - id: L3
+    requiredRoles: []
+    title: DEPENDENCIAS
+    instruction: >
+      Declara qué afirmación se apoya en cuál. Si una cadena de apoyos vuelve
+      sobre sí misma, el documento razona en círculo y este nivel es donde se ve.
+    fanout:
+      min: 1
+      max: 50
+  - id: L4
+    requiredRoles: []
+    title: MANUSCRITO
+    instruction: >
+      Escribe el texto. Cada figura viene con su pie y cada afirmación con la
+      referencia o el dato que la sostiene.
+    fanout:
+      min: 1
+      max: 60
+
+# La autorrevisión: qué tiene que comprobar quien entrega, y con qué acción.
+#
+# La escalera comprueba los saltos ENTRE niveles. Nadie comprueba que el
+# manuscrito responda la pregunta que se declaró en L0, porque no hay peldaño
+# anterior contra el que reconciliar. Eso es lo que cierra esta sección.
+selfReview:
+  criteria:
+    - check: Toda cita tiene fuente localizable y la fuente dice lo que se le atribuye
+      how: >
+        Recorre las citas una a una, abre la fuente y contrasta la afirmación con
+        el pasaje. Una fuente que no se pudo abrir cuenta como no comprobada.
+      evidence: medida
+    - check: El formato de referencias es el declarado y es uniforme en todo el documento
+      how: Compara todas las entradas contra el estilo declarado en L1.
+      evidence: medida
+    - check: No hay afirmaciones que se contradigan entre secciones
+      how: >
+        Contrasta cada afirmación de L2 con las demás, en particular las de
+        secciones distintas que hablen del mismo objeto.
+      evidence: juicio
+    - check: La estructura entregada es la que se declaró en L1
+      evidence: juicio
+    - check: El manuscrito responde la pregunta declarada en L0, y no otra
+      evidence: juicio
+  groundingCheck: true
+  groundingScope: alguna fuente, cita, dato o afirmación
+  assumptionsMustDeclare: true

package/catalogo-de-ejemplo/arquetipos/inventario-funcional.yaml

@@ -0,0 +1,42 @@
+# Inventario funcional de un sistema existente.
+#
+# Antes de migrar, qué hace hoy el sistema: las funciones que no se pueden
+# perder. Es la línea de partida del plan de migración.
+name: inventario-funcional
+version: 1.1.0
+description: >-
+  Qué hace hoy un sistema existente, función a función, antes de migrarlo: lo que no se puede perder. Es el primer artefacto de trabajo del carril de migración. Elígelo para describir un sistema que ya existe; para pedir algo nuevo corresponde un PRD.
+tags: [proceso, migracion, inventario]
+
+kinds:
+  - name: objetivo
+    describes: "pieza de la solicitud (L0): qué sistema se inventaría y para qué migración"
+  - name: funcion
+    describes: algo que el sistema hace hoy y que alguien usa
+  - name: documento
+    describes: el fichero del inventario, en la carpeta de trabajo del paso
+
+extractors:
+  - mechanism: path
+    kind: documento
+    pattern: "<nombre>.md"
+
+levels:
+  - id: L0
+    requiredRoles: []
+    title: SISTEMA
+    instruction: >
+      Declara qué sistema se inventaría, dónde vive y hacia dónde se migra.
+  - id: L1
+    requiredRoles: []
+    title: FUNCIONES
+    instruction: >
+      Declara las funciones del sistema actual, cada una con quién la usa, y el
+      fichero del inventario (tipo `documento`, con su `location`). Una función
+      que nadie usa se declara igual: decidir si se pierde es del plan. Una
+      función puede sembrar el índice de requisitos del sistema con los mismos
+      atributos que un requisito del PRD (`tipo`, `requisito`, `titulo`,
+      `sale_de` y los demás): aprobar el inventario los acuerda.
+    fanout:
+      min: 1
+      max: 80