MEV - Compilador de Estado e Grafo do Cérebro da Empresa
CLI em Rust que valida um corpus de conhecimento multi-repositório e compila suas visões derivadas — estado de planejamento, o grafo de blocos entre repositórios e a saída legível por máquina que serve de portão para o indexador RAG.
Overview
O MEV começou como um validador de Markdown e se tornou a metade que escreve do cérebro da empresa. Ele lê um corpus de Markdown e MDX espalhado por dezenove repositórios, valida esse corpus em cinco eixos independentes — estrutura do frontmatter OKF, integridade de `[[wikilinks]]` e referências de arquivo, o grafo de conhecimento `scope:doc_id`, o esquema do estado de planejamento de cada repositório e a cobertura bidirecional de `index.md` — e então compila o que leu em visões derivadas que outras ferramentas consomem. A metade compiladora é a parte interessante. O `emit-state` é um compilador de ponto fixo: ele resolve o estado de planejamento entre repositórios — status de blocos, arestas de dependência, participação em épicos — até que a saída pare de mudar, e então insere as tabelas geradas de volta nos documentos Markdown que as descrevem. Isso significa que a tabela de sequência de um roadmap não é prosa mantida à mão que se desatualiza; é saída compilada, regenerada a partir dos mesmos arquivos `state.json` que os painéis leem. O `emit-graph` e o `emit-block-graph` emitem o grafo de conhecimento e o grafo de dependências de blocos como artefatos JSON. Como a saída é legível por máquina (`--json` em todos os caminhos de validação, com saída diferente de zero em qualquer diagnóstico de severidade de erro), o MEV funciona como portão, e não como relatório. O indexador RAG se recusa a reconstruir sobre um corpus que falha na validação, e o hook de push bloqueia erros novos desde o último push bem-sucedido — então uma referência quebrada é detectada no momento em que é introduzida, e não descoberta depois por um leitor. A restrição de projeto o tempo todo é que um validador em que ninguém confia acaba desativado. Cada verificação tem escopo para relatar apenas o que consegue provar, e os diagnósticos nomeiam o arquivo, a linha e a regra.
Technical Stack
Núcleo
- ▸Rust
- ▸clap
- ▸serde
- ▸okf-core (dependência por caminho)
Validação
- ▸Frontmatter OKF
- ▸Resolução de wikilinks
- ▸Integridade do grafo de conhecimento
- ▸Esquema de estado
- ▸Cobertura de index.md
Compilação
- ▸emit-state (ponto fixo)
- ▸emit-graph
- ▸emit-block-graph
- ▸Inserção por sentinela
Testes
- ▸cargo nextest
- ▸Testes de regressão com arquivos golden
Key Features
Cinco eixos de validação independentes — estrutura do frontmatter, integridade de links, grafo de conhecimento, esquema do estado de planejamento e cobertura de índices
O compilador de ponto fixo `emit-state` resolve o estado de planejamento entre repositórios até a saída parar de mudar
As tabelas geradas são inseridas de volta nos documentos que as descrevem, então roadmaps compilam em vez de se desatualizar
`emit-graph` e `emit-block-graph` emitem o grafo de conhecimento e o grafo de dependências de blocos como artefatos JSON
`--json` legível por máquina em todos os caminhos, com saída diferente de zero em qualquer diagnóstico de severidade de erro
Funciona como portão: o indexador RAG se recusa a reconstruir sobre um corpus que falha na validação
Comandos de ciclo de vida de épicos (defer, resume, complete, sync) reconciliam o status do registro com os blocos membros nos dois sentidos
Cada diagnóstico nomeia o arquivo, a linha e a regra — um validador em que ninguém confia acaba desativado
Technical Challenges
Fazer o `emit-state` convergir: a regeneração ingênua pode oscilar quando duas visões derivadas se referenciam mutuamente
Inserir conteúdo gerado em Markdown escrito à mão sem destruir a prosa ao redor
Dar escopo a cada verificação para relatar apenas o que ela consegue provar — um falso positivo custa mais confiança do que um erro não detectado
Validar um corpus espalhado por dezenove repositórios onde cada diretório de planejamento é um link simbólico