Tekton — arrebitamento de arquitetura em co-design com o agente

Tekton — co-design de arquitetura sobre um modelo compartilhado

O que é

Um substrato para a parceria humano↔agente em arquitetura. O design reside em um único modelo YAML que ambos editamos; o git é o caminho de ida e volta. Você vê (visualizador HTML); eu leio e escrevo o mesmo modelo. Pensamos sobre o mesmo contexto.

A falha que ele corrige: um documento HTML/SVG feito à mão é uma renderização terminal — você não pode percorrer, consultar ou editá-lo de volta, e seus diagramas não carregam significado. Tekton move o modelo ativo a montante da renderização.

Motor

scripts/tekton.py (Python 3, pyyaml). Ontologia em references/ontology.md.

python3 scripts/tekton.py validate <modelo.arch.yaml>       # verificação de integridade
python3 scripts/tekton.py lint     <modelo.arch.yaml>       # v0.2 — funções de aptidão; sai com 1 em violação
python3 scripts/tekton.py stats    <modelo.arch.yaml>       # contagens de nós/arestas/status/regras
python3 scripts/tekton.py views                            # lista as 6 visões
python3 scripts/tekton.py mermaid  <modelo.arch.yaml> <visão># mermaid bruto (embutir/agente)
python3 scripts/tekton.py render   <modelo.arch.yaml> [-o saida.html]  # visualizador HTML na marca
python3 scripts/tekton.py query    <modelo.arch.yaml> <de> <para>      # caminho entre camadas

Atualizações da ontologia v0.2 (da revisão de arquitetura)

• Contenção — parent: em qualquer nó + tipo boundary; o visualizador renderiza grupos aninhados, clique duplo para recolher/expandir (drill-down estilo C4).
• Ciclo de vida — status: nos nós (current|target|deprecated; target renderiza tracejado = como-está/como-deveria-ser em um modelo) e campos ADR completos de Nygard nas decisões (context, consequences, status, supersedes).
• Qualidades — bloco qualities:; NFRs constrains elementos; exibido no painel de detalhes
  • visão dedicada.
• Funções de aptidão — bloco rules: (forbid-dep, no-cycle, layer-order); tekton lint é integrável em CI (saída 1). O verificador independente do loop de design.

Como o agente usa em uma sessão de design

1. Localizar/criar o modelo: <projeto>/docs/design/<nome>.arch.yaml (ou examples/ para rascunho).
2. Mutar enquanto pensamos — adicionar/ajustar nós, arestas, decisões diretamente no YAML conforme a conversa revela componentes, fluxos, dados, infraestrutura e ADRs.
3. validate + lint após cada edição substancial (referências pendentes, tipos ruins, regras de aptidão).
4. render, então — ANTES de apresentar o visualizador como correto — execute a auditoria geométrica: bash tests/visual-audit.sh <modelo.arch.yaml>. Ele renderiza cada visão em modo headless e FALHA em sobreposições de nós ou capturas vazias. Afirmar que "o diagrama está correto" sem isso é exatamente a falha que o primeiro dogfood detectou (arestas desconectadas em grupos, nós duplicados — invisíveis a sondas de contagem de DOM, detectadas apenas pela geometria). Vincule profundamente uma visão com #<visão> na URL.
5. query para responder perguntas de rastreabilidade ("o que isso toca?") em vez de adivinhar.
6. Direcionar → repetir. O humano edita o YAML ou a intenção do visualizador; o diff do git é a entrega.

Resíduos cosméticos conhecidos (não falhas de auditoria): arestas de loop de jornada fazem o ELK quebrar o ciclo em uma etapa arbitrária (um loop deve quebrar em algum lugar); rótulos de arestas paralelas adjacentes podem ficar próximos em grupos densos.

Convenções

• Arquivos de modelo: *.arch.yaml. Visualizador renderizado: *.view.html (gitignore ou commit — você decide).
• Um modelo por sistema delimitado; vincule sistemas com nós external + arestas uses.
• Decisões (ADRs) são nós de primeira classe — fixe-as ao que elas govern.
• Relatórios HTML Categoria-C tornam-se uma exportação a jusante de um modelo, não a fonte da verdade.

Renderização — por que não Mermaid

O visualizador principal é um renderizador personalizado, não Mermaid. O teto de tematização do Mermaid não consegue expressar o Sistema de Design Broomva (eixo azul OKLCH, cartões foscos, vidro merecido, brilho de cometa) e seu layout dagre degrada em grafos densos. Em vez disso: elkjs calcula o layout no navegador (JS puro → a saída continua sendo um único arquivo HTML autocontido), e os nós são desenhados como cartões foscos Broomva (vidro reservado para o painel de detalhes flutuante, conforme a regra de "vidro é merecido" do DS). Os tokens de design são embutidos a partir do Sistema de Design Broomva. tekton mermaid permanece APENAS como um alvo descartável para embutir/legível por agente.

Roteiro (v0 → v2)

• v0.2 (agora): Modelo YAML · validar + lint (funções de aptidão) · 6 visões · visualizador elkjs na marca (recolher/expandir contenção, como-está/como-deveria-ser, clique para rastrear, painel de detalhes em vidro) · consulta entre camadas · fallback Mermaid para embutir.
• v1: ida e volta bidirecional (arrastar/editar no visualizador → serializar de volta para YAML); servidor MCP (mutações validadas para que o agente não possa emitir um modelo inválido); fornecer o Sistema de Design Broomva completo para uma tela interativa React-Flow.
• v2: CRDT (loro) co-edição humano↔agente em tempo real; sincronização ao vivo no Prosopon como uma superfície.

Status

v0 dogfood — ferramenta de design interna. Skillify (testada + registrada) assim que o loop de design tiver sido usado em ≥3 sistemas reais (regra-de-três).