tekton — sustrato compartido de arquitectura para codiseño

Tekton — codiseño de arquitectura sobre un modelo compartido

Qué es

Un sustrato para la asociación humano↔agente en arquitectura. El diseño vive en un solo modelo YAML que ambos editamos; git es el viaje de ida y vuelta. Tú ves el modelo (visor HTML); yo leo y escribo el mismo modelo. Pensamos sobre el mismo contexto.

El fallo que corrige: un documento HTML/SVG escrito a mano es una representación terminal — no se puede recorrer, consultar ni editar de vuelta, y sus diagramas no tienen significado. Tekton mueve el modelo vivo río arriba de la representación.

Motor

scripts/tekton.py (Python 3, pyyaml). Ontología en references/ontology.md.

python3 scripts/tekton.py validate <modelo.arch.yaml>       # verificación de integridad
python3 scripts/tekton.py lint     <modelo.arch.yaml>       # v0.2 — funciones de fitness; sale con 1 si hay violación
python3 scripts/tekton.py stats    <modelo.arch.yaml>       # conteos de nodos/aristas/estado/reglas
python3 scripts/tekton.py views                            # lista las 6 vistas
python3 scripts/tekton.py mermaid  <modelo.arch.yaml> <view># mermaid plano (para incrustar/agente)
python3 scripts/tekton.py render   <modelo.arch.yaml> [-o salida.html]  # visor HTML con la marca
python3 scripts/tekton.py query    <modelo.arch.yaml> <desde> <hasta>    # ruta entre capas

Mejoras de ontología v0.2 (desde la revisión de arquitectura)

• Contención — parent: en cualquier nodo + tipo boundary; el visor renderiza grupos anidados, doble clic para colapsar/expandir (drill-down estilo C4).
• Ciclo de vida — status: en nodos (current|target|deprecated; target se renderiza con línea discontinua = estado actual/objetivo en un mismo modelo) y campos completos de ADR Nygard en decisiones (context, consequences, status, supersedes).
• Cualidades — bloque qualities:; los NFR constrains elementos; se muestran en el panel de detalles + vista dedicada.
• Funciones de fitness — bloque rules: (forbid-dep, no-cycle, layer-order); tekton lint es integrable en CI (sale con 1). El verificador independiente del bucle de diseño.

Cómo lo usa el agente en una sesión de diseño

1. Localizar/crear el modelo: <proyecto>/docs/design/<nombre>.arch.yaml (o examples/ para pruebas rápidas).
2. Mutar mientras pensamos — añadir/ajustar nodos, aristas, decisiones directamente en el YAML a medida que la conversación revela componentes, flujos, datos, infraestructura y ADRs.
3. validate + lint después de cada edición sustancial (referencias colgadas, tipos incorrectos, reglas de fitness).
4. render, luego — ANTES de presentar el visor como correcto — ejecutar la auditoría geométrica: bash tests/visual-audit.sh <modelo.arch.yaml>. Renderiza cada vista sin cabeza y FALLA si hay solapamiento de nodos o capturas vacías. Afirmar que "el diagrama es correcto" sin esto es exactamente el fallo que detectó el primer dogfood (aristas desconectadas en grupos, nodos duplicados — invisibles para sondas de conteo DOM, detectados solo por geometría). Enlace profundo a una vista con #<view> en la URL.
5. query para responder preguntas de trazabilidad ("¿qué toca esto?") en lugar de adivinar.
6. Dirigir → repetir. El humano edita el YAML o la intención del visor; git diff es la transferencia.

Residuos cosméticos conocidos (no son fallos de auditoría): las aristas de bucle en journeys hacen que ELK rompa el ciclo en un paso arbitrario (un bucle debe romperse en algún lugar); las etiquetas de aristas paralelas adyacentes pueden quedar juntas en grupos densos.

Convenciones

• Archivos de modelo: *.arch.yaml. Visor renderizado: *.view.html (gitignore o commit — decisión tuya).
• Un modelo por sistema acotado; enlazar sistemas con nodos external + aristas uses.
• Las decisiones (ADRs) son nodos de primera clase — fijarlas a lo que govern (gobiernan).
• Los informes HTML de Categoría C se convierten en una exportación aguas abajo del modelo, no en la fuente de verdad.

Renderizado — por qué no Mermaid

El visor principal es un renderizador personalizado, no Mermaid. El techo de tematización de Mermaid no puede expresar el Sistema de Diseño de Broomva (eje azul OKLCH, tarjetas mate, cristal ganado, resplandor cometa) y su diseño dagre se degrada en grafos densos. En su lugar: elkjs calcula el diseño en el navegador (JS puro → la salida sigue siendo un único archivo HTML autocontenido), y los nodos se dibujan como tarjetas mate de Broomva (cristal reservado para el panel flotante de detalles, según la regla de "el cristal se gana" del DS). Los tokens de diseño se incrustan desde el Sistema de Diseño de Broomva. tekton mermaid se mantiene SOLO como un objetivo desechable para incrustar/agente.

Hoja de ruta (v0 → v2)

• v0.2 (ahora): Modelo YAML · validate + lint (funciones de fitness) · 6 vistas · visor elkjs con la marca (colapsar/expandir contenedores, estado actual/objetivo, clic para rastrear, panel de detalles con cristal) · consulta entre capas · incrustación de respaldo Mermaid.
• v1: ida y vuelta bidireccional (arrastrar/editar en el visor → serializar de vuelta a YAML); servidor MCP (mutaciones validadas para que el agente no pueda emitir un modelo inválido); incorporar el Sistema de Diseño completo de Broomva para un lienzo interactivo React-Flow.
• v2: CRDT (loro) para coedición humano↔agente en tiempo real; sincronización en vivo con Prosopon como superficie.

Estado

dogfood v0 — herramienta interna de diseño. Skillificar (probar + registrar) una vez que el bucle de diseño se haya usado en ≥3 sistemas reales (regla de tres).