Governance

Governança e Inteligência Sintética (DevGovOps)

Este projeto implementa uma arquitetura DevGovOps, onde a governança não é um processo externo burocrático, mas parte integrante do código-fonte, legível tanto por humanos quanto por agentes de IA.

O Yby CLI é "AI-Native". Ele cria uma camada semântica (Synapstor) otimizada para LLMs e Agentes em IDEs.

---

🌟 Visão

Queremos que qualquer agente de IA (Claude, ChatGPT, IDE Agents) que entre neste repositório seja capaz de:

1. Entender o negócio e o contexto técnico instantaneamente.
2. Respeitar as decisões arquiteturais passadas.
3. Evoluir o conhecimento do projeto de forma estruturada.

Benefícios Reais

• Integração sem preparo: Um novo Agente de IA (ou humano) abrindo o projeto pela primeira vez sabe exatamente como verificar a saúde (yby doctor), onde estão os logs e qual a estratégia de branches, apenas lendo o .synapstor.
• Consciência do contexto: A IA não vai sugerir "instalar Postgres via Docker" se ler um ADR no .synapstor declarando que "Usamos RDS Gerenciado".

---

🧠 Synapstor (.synapstor/)

O diretório .synapstor é a fonte canônica da verdade.

Estrutura

• 00_PROJECT_OVERVIEW.md: O "Manual de Instruções" do projeto.
• 02_BACKLOG_AND_DEBT.md: Backlog e Dívida Técnica.
• 01_EXECUTION_LOG.md: Diário de bordo imutável das ações dos agentes.
• UKI_SPEC.md: A especificação dos UKIs (formato, tipos, status e seções de cada tipo).
• .uki/: Os UKIs, com subpastas por domínio.

O overview e o backlog também vão aos plugins que declaram "consome_contexto": true no manifesto (veja Arquitetura).

UKIs (Unidades de Conhecimento Interligadas)

Os UKIs são unidades atômicas de conhecimento: uma regra, decisão, padrão, métrica ou referência que continua valendo. A especificação pede o nome .synapstor/.uki/[<dominio>/]UKI-<timestamp>-<slug>.md e um frontmatter em português, que é o que o capture e o study geram (o Synapstor lê qualquer .md de .synapstor/.uki e das subpastas):

---
id: cli.ux.estrutura-flag-json
tipo: regra | decisao | padrao | metrica | referencia
status: rascunho | ativo | obsoleto
criado_em: AAAA-MM-DD
atualizado_em: AAAA-MM-DD
tags: [cli, json]
---

• Tipos: cada tipo tem as suas seções ## (a regra tem Contexto, Enunciado e Exceções; a decisão é um ADR leve com Problema, Opções, Decisão e Consequências). O yby synapstor quality pontua por elas e diz qual falta.
• Formatos antigos: o frontmatter em inglês (uki_id, type, created_at...) e as linhas em negrito (**ID:**, **Tipo:**) continuam sendo lidos.
• Busca: yby synapstor index indexa os UKIs (e as páginas de docs/wiki) com embeddings, para o yby synapstor search e o Bard.

---

🤖 Agentes (Matrix Protocol)

O yby-cli é desenvolvido sob o Matrix Protocol. Estas são as personas que operam no repositório:

1. Governance Steward (O Bibliotecário)

• Função: Organizar o .synapstor e garantir conformidade.
• Frase: "Isso conflita com o UKI cli.ux.colors..."

2. DevEx Guardian (O Advogado do Usuário)

• Função: Garantir usabilidade e documentação clara.
• Frase: "Esse erro 500 não ajuda o usuário. Sugira uma ação."

3. Platform Engineer (A Rocha)

• Função: Implementação técnica segura, scripts de build e release.
• Frase: "O linter falhou. Não posso aprovar."

---

🧠 Integração AI

O CLI atua como um "Arquiteto Virtual" conectando-se ao seu provedor de IA preferido:

Prioridade	Provedor	Requisito
1	Ollama (Local)	localhost ou OLLAMA_HOST
2	Claude Code CLI	claude no PATH
3	Gemini CLI	gemini no PATH
4	Google Gemini	GEMINI_API_KEY
5	OpenAI	OPENAI_API_KEY
6	Amazon Bedrock	Binário yby-cloud (build tag aws) e credenciais AWS configuradas

A ordem muda com ai.priority no ~/.yby/config.yaml.

Ao rodar yby init, ele gera um .synapstor rico contendo ADRs (Decisões Arquiteturais) e Skills (UKI_AGENT_SKILLS.md) ensinando a IA a operar este projeto específico.

---

🔄 Ciclo de Vida

1. Descoberta: Padrão identificado.
2. Captura (yby synapstor capture "texto" ou yby synapstor study "tópico"): Documentado como UKI. O Synapstor monta o frontmatter: ID, tipo e tags vêm da IA, o status nasce rascunho e as datas são as do dia. Depois, yby synapstor index põe o UKI novo na busca e no Bard.
3. Validação: Revisado pelo Governance Steward, o UKI passa a status: ativo.
4. Aplicação: Os agentes usam o UKI como regra.
5. Evolução: O UKI é atualizado se o padrão mudar (com atualizado_em do dia), ou status: obsoleto quando deixa de valer. O yby synapstor decay aponta os UKIs sem atividade no git há mais de 90 dias ou cujo código citado mudou depois da nota.

O yby uki capture do core é outra coisa: a partir da descrição do projeto, pede à IA um rascunho da estrutura de governança (overview, persona e UKIs) e grava os arquivos como a IA os escreveu, sem o frontmatter que o Synapstor monta. Grava por cima, sem conferir: sobrescreve o 00_PROJECT_OVERVIEW.md que já existir.