MEDE-CLI

MEDE-CLI é uma ferramenta de linha de comando para evolução documental causal assistida por LLMs, baseada na metodologia MEDE (Metodologia de Evolução Documental Estruturada).

O objetivo do projeto é permitir que a documentação de engenharia de software evolua de forma supervisionada, rastreável e consistente, acompanhando decisões reais de projeto ao longo do tempo.

✦ Motivação

Projetos de software frequentemente enfrentam:

documentação desatualizada ou inconsistente;
decisões arquiteturais não registradas;
perda de entendimento do estado real do sistema;
divergência entre código, decisões e documentação;
uso descontrolado de LLMs para geração de conteúdo técnico.

O MEDE-CLI organiza a evolução documental como um processo causal estruturado, no qual mudanças são propostas, analisadas e aprovadas antes de serem aplicadas.

✦ Instalação

Requisitos

Node.js ≥ 20 (testado em 20 e 22);
npm (acompanha o Node.js);
Toolchain de compilação nativa para o better-sqlite3. Na maioria das plataformas o pacote usa binários pré-compilados; se não houver binário para o seu ambiente, será necessário ter Python 3 e um compilador C++ instalados (build-essential no Linux, Xcode Command Line Tools no macOS ou Visual Studio Build Tools no Windows).

Instalação global (via npm)

npm install -g mede-cli
mede-cli --help

Execução pontual (sem instalar)

npx mede-cli --help

A partir do código-fonte

git clone https://github.com/mozaru/mede-cli.git
cd mede-cli
npm install
npm run build        # gera dist/cli/index.mjs
npm link             # disponibiliza o comando `mede-cli` globalmente

Durante o desenvolvimento é possível executar sem compilar:

npm run dev -- --help    # equivale a `mede-cli --help`

Configuração de credenciais da LLM

As credenciais dos provedores de LLM podem ser fornecidas de três formas no mede.config.json, configurando a propriedade llm.auth:

apiKey (Padrão): A chave de API é lida diretamente de uma variável de ambiente definida em llm.apiKeyEnv.
```
export OPENAI_API_KEY="sk-..."
```
oauth: Autenticação interativa via OAuth. Roda-se o comando mede-cli llm login para autenticar e armazenar as credenciais cifradas no cofre local (~/.mede/keys.json).
- Para Azure e Google Cloud (Vertex AI), usa-se o fluxo Device Code.
- Para OpenRouter, usa-se o fluxo PKCE (que abre o navegador e inicia um servidor local de callback).
- Configuração: No arquivo mede.config.json, adicione o bloco oauth dentro de llm:
```
"llm": {
  "provider": "openrouter",
  "model": "google/gemini-2.5-pro",
  "endpoint": "https://openrouter.ai/api/v1",
  "apiKeyEnv": "OPENROUTER_API_KEY",
  "auth": "oauth",
  "oauth": {
    "clientId": "seu-client-id-openrouter",
    "callbackPort": 8765
  }
}
```
  Nota: A porta de callback callbackPort é opcional e padronizada para 8765.
adc (Application Default Credentials): Utiliza as credenciais padrão do ambiente local (ex: do Google Cloud SDK obtido via gcloud auth application-default print-access-token). Não armazena nada no cofre do MEDE-CLI.

Console interativo

Executar mede-cli sem argumentos abre um console interativo (REPL) que reaproveita exatamente os mesmos comandos:

$ mede-cli
MEDE-CLI — console interativo
mede> status
mede> cycle -p "novo ciclo"
mede> approve
mede> exit

Digite help para a lista de comandos, <comando> --help para detalhes e exit/quit para sair. Qualquer comando explícito (ex.: mede-cli status) mantém o comportamento one-shot, usado por scripts, CI e pela flag --json.

Saída em JSON (para scripts)

Qualquer comando aceita a flag global --json (posicionada antes do subcomando), que emite o resultado e os erros em JSON estável em vez de texto:

mede-cli --json status
# sucesso → {"ok":true,"output":"..."}
# erro    → {"ok":false,"error":"..."}

O código de saída continua diferente de zero em caso de falha, permitindo combinar o JSON com a verificação do status de saída em scripts.

Para detalhes de empacotamento, publicação no npm e versionamento, consulte DISTRIBUICAO.md.

✦ Publicações Relacionadas

Os fundamentos conceituais do MEDE-CLI, da metodologia MEDE e da linha de pesquisa relacionada podem ser encontrados nos seguintes trabalhos:

MEDE — Metodologia de Engenharia Documental Evolutiva
https://doi.org/10.5281/zenodo.19007113
Engenharia de Software 4.0 e Complexidade Essencial
https://doi.org/10.5281/zenodo.19101645
Janus e MEDE — Governança do Conhecimento da Solução e Projeção Tecnológica
https://doi.org/10.5281/zenodo.19110314

Lista completa de publicações:

https://11tech.com.br/publications.html

✦ Conceito Central

Toda alteração documental no MEDE-CLI é tratada como um change-set pendente.

A ferramenta:

propõe mudanças estruturadas;
organiza ciclos de revisão;
aplica alterações somente após aprovação humana.

Nenhuma modificação é realizada automaticamente.

✦ Princípios de Projeto

Supervisão humana obrigatória.
Evolução documental orientada por causalidade.
Separação entre documentação histórica e documentação viva.
Estado do projeto sempre reconstruível.
Independência de fornecedor de LLM.
Arquitetura open-source extensível.
Compatibilidade com fluxos reais de engenharia.

✦ Ciclo Metodológico

O comando central do projeto é:

`mede-cli cycle`

Ele inicia um ciclo metodológico supervisionado de evolução documental do projeto.

O comportamento depende do estado atual:

se o projeto ainda não possui base documental → inicia a criação da baseline;
se já existe baseline → inicia um novo ciclo de evolução documental.

O ciclo trabalha com etapas sequenciais e dependentes entre si.

Ordem do ciclo

geração de ata;
geração de ADR;
geração de ESM;
geração de log de entrega (LEG);
atualização de requisitos funcionais;
atualização de requisitos não funcionais;
atualização do modelo de dados;
atualização do cronograma;
atualização de visão e escopo;
atualização do README;
atualização da situação atual do projeto.

obs: a quantidade de atas existentes indica quantos ciclos ja existiram, entao o numero do ciclo corrente é a quantiadade de atas + 1. O documento entendimento-indical, quando necessário, usa-se o ciclo 0.

Dependências entre etapas

Cada etapa utiliza apenas os documentos relevantes para aquele tipo de geração ou atualização.

ATA
- apenas contexto do projeto e instrução do usuário

ADR
- ATA

ESM
- ATA

LEG
- ATA + ESM

requisitos-funcionais.md
- ATA + ADR

requisitos-nao-funcionais.md
- ATA + ADR

modelo-de-dados.md
- ATA + ADR + requisitos-funcionais.md + requisitos-nao-funcionais.md

cronograma.md
- ATA + ADR + ESM + requisitos-funcionais.md + requisitos-nao-funcionais.md + modelo-de-dados.md

visao-e-escopo.md
- ATA + ADR + requisitos-funcionais.md + requisitos-nao-funcionais.md + modelo-de-dados.md

readme.md
- ATA + ADR + visao-e-escopo.md

situacao-atual.md
- ATA + ADR + requisitos-funcionais.md + requisitos-nao-funcionais.md + modelo-de-dados.md + visao-e-escopo.md

A mesma lógica pode ser lida de forma resumida assim:

ATA -> ADR
ATA -> ESM
ATA + ESM -> LEG
ATA + ADR -> requisitos-funcionais.md
ATA + ADR -> requisitos-nao-funcionais.md
ATA + ADR + requisitos-funcionais.md + requisitos-nao-funcionais.md -> modelo-de-dados.md
ATA + ADR + ESM + requisitos-funcionais.md + requisitos-nao-funcionais.md + modelo-de-dados.md -> cronograma.md
ATA + ADR + requisitos-funcionais.md + requisitos-nao-funcionais.md + modelo-de-dados.md -> visao-e-escopo.md
ATA + ADR + visao-e-escopo.md -> readme.md
ATA + ADR + requisitos-funcionais.md + requisitos-nao-funcionais.md + modelo-de-dados.md + visao-e-escopo.md -> situacao-atual.md

Artefatos produzidos no ciclo

Durante um ciclo, o MEDE-CLI pode:

gerar atas de reunião (min-*);
propor decisões arquiteturais (adr-*);
propor especificações de evolução/manutenção (esm-*);
propor logs de entrega (leg-*);
sincronizar documentos vivos;
atualizar cronograma, visão e escopo, README e situação atual.

Regras de progressão

Se uma etapa não produzir conteúdo relevante:

artefatos opcionais podem ser ignorados;
diffs vazios não geram atualização.

Ainda assim, a passagem para a próxima etapa depende de ação explícita do usuário.

Cada fase só avança após resolução dos change-sets pendentes.

✦ Modelo Transacional do Ciclo

Cada etapa possui seu próprio ciclo interno:

a LLM gera uma proposta inicial;
o usuário pode refinar quantas vezes quiser;
o usuário pode aprovar ou rejeitar;
após aprovação ou rejeição, a etapa seguinte é preparada.

Comportamento por etapa

Na etapa de ATA:

approve avança para a próxima fase;
reject encerra o ciclo.

Nas demais etapas:

approve aceita a proposta atual e avança;
reject ignora a proposta atual e avança;
mesmo artefatos vazios podem ser aprovados ou rejeitados.

Cada etapa mantém:

histórico de refinamentos;
mensagens trocadas com a LLM;
arquivos anexados;
change-sets pendentes;
estado do artefato atual.

✦ Commit e Rollback

Ao iniciar um ciclo, o MEDE-CLI cria um snapshot completo de todos os documentos vivos.

Exemplos:

readme.md
situacao-atual.md
requisitos-funcionais.md
requisitos-nao-funcionais.md
modelo-de-dados.md
cronograma.md
visao-e-escopo.md

Também entram no snapshot quaisquer outros documentos marcados como living documents pela ontologia do projeto.

Não entram no snapshot:

ata-*
adr-*
esm-*
leg-*

Esses documentos históricos são apenas criados durante o ciclo.

`mede-cli commit`

Finaliza o ciclo e mantém todos os arquivos aprovados.

Após commit:

o snapshot é descartado;
os artefatos históricos permanecem;
os documentos vivos permanecem atualizados;
o ciclo é encerrado.

`mede-cli rollback`

Restaura integralmente o estado anterior ao ciclo.

Após rollback:

todos os documentos vivos voltam ao snapshot inicial;
artefatos históricos criados no ciclo são removidos;
documentos vivos criados durante o ciclo são removidos;
o ciclo é encerrado.

✦ Comandos Disponíveis

`mede-cli init`

Cria a baseline operacional e a configuração inicial do projeto.

mede-cli init -p "contexto adicional" -f "file1;dir;file2"

Parâmetros:

-p, --prompt: prompt adicional enviado à LLM;
-f, --files: arquivos ou diretórios adicionados ao contexto.

`mede-cli cycle`

Inicia um novo ciclo metodológico.

mede-cli cycle -p "ajustes desejados" -f "ata.txt;docs/"

Parâmetros:

-p, --prompt
-f, --files

`mede-cli status`

Mostra o estado operacional atual do ciclo.

Exemplo:

Cycle: aberto
Phase: ATA
Artifact: ata-2026-04-04.md
State: aguardando approve/reject
Proposal: não vazia
Refinements: 3
Changed files: 1
Created files: 1
Auto-approve: não

Available actions:
- refine
- approve
- reject
- rollback

`mede-cli refine`

Refina a etapa atual.

mede-cli refine -p "explique melhor a decisão" -f "reuniao.md"
mede-cli refine -r

Parâmetros:

-p, --prompt
-f, --files
-r, --reset

O reset:

limpa histórico da conversa;
limpa anexos;
remove change-sets pendentes;
restaura o artefato da etapa;
remove arquivos criados pela etapa.

`mede-cli approve`

Aprova a etapa atual.

mede-cli approve
mede-cli approve -a

Parâmetros:

-a, --all: aprova automaticamente todas as etapas seguintes.

`mede-cli reject`

Rejeita a etapa atual.

mede-cli reject
mede-cli reject -a

Parâmetros:

-a, --all: rejeita automaticamente todas as etapas seguintes.

`mede-cli pending`

Lista os trecho-diff pendentes do change-set atual.

Exemplo:

[1] requisitos-funcionais.md
replace lines 10-18
status: pending

[2] requisitos-funcionais.md
insert after line 44
status: pending

`mede-cli apply`

Aplica trecho-diff pendente.

mede-cli apply
mede-cli apply -a

`mede-cli discard`

Descarta trecho-diff pendente.

mede-cli discard
mede-cli discard -a

`mede-cli files`

Lista os arquivos alterados ou criados no ciclo atual.

mede-cli files
mede-cli files -b

Parâmetros:

-b, --backup: mostra os arquivos do snapshot inicial.

`mede-cli diff`

Mostra o diff do arquivo informado.

mede-cli diff readme.md

`mede-cli cat`

Mostra o conteúdo do arquivo informado.

mede-cli cat readme.md
mede-cli cat readme.md -b

`mede-cli llm`

Inspeciona a configuração e exibe o status de modelos/provedores LLM ativos.

`mede-cli llm login`

Inicia o fluxo de login interativo via OAuth (fluxo Device Code para Azure/Google ou fluxo PKCE com abertura de navegador local para OpenRouter) e armazena os tokens de acesso com segurança no cofre de segredos local.

`mede-cli llm logout`

Limpa as credenciais OAuth locais salvas no cofre para o provedor ativo.

`mede-cli llm test`

Executa um prompt isolado sem afetar o contexto atual.

mede-cli llm test -p "explique este requisito"

`mede-cli config`

Mostra o conteúdo atual da configuração.

`mede-cli config init`

Cria mede.config.json caso ainda não exista.

`mede-cli config apply`

Aplica alterações feitas manualmente no arquivo de configuração.

✦ Semântica dos Níveis de Operação

Nível trecho-diff:
- pending
- apply
- discard

Nível etapa:
- refine
- refine --reset
- approve
- reject

Nível ciclo:
- cycle
- commit
- rollback

✦ Convenções de Backlog, Situação Atual e Rastreabilidade

O MEDE-CLI diferencia:

itens em formação de conhecimento;
backlog formal rastreável;
registros históricos imutáveis.

Durante entendimento inicial e atas, os itens ainda podem ser reorganizados, fundidos, cancelados ou reclassificados.

Por isso, documentos como:

entendimento-inicial.md
atas (min-*)

registram apenas:

descrição;
natureza;
tipo de intervenção;
tags opcionais.

O identificador definitivo e imutável surge apenas quando o item passa a existir formalmente no backlog operacional do projeto, em documentos como:

esm-*;
leg-*;
situacao-atual.md.

Padrão de identificação formal

<DOC>-<AAAAMMDD>-<CICLO>-<NAT>-<TIP>-<NNNN>

Exemplos:

DEI-20260201-001-RF-BLI-0001
ESM-20260301-001-RF-COR-0001
ESM-20260301-001-UX-AJU-0003
ESM-20260301-001-AR-EVO-0002
LEG-20260310-003-OP-COR-0002
SAT-20260315-005-AR-EVO-0001

Convenções

Natureza:
RF = requisito funcional
NF = requisito não funcional
RN = regra de negócio
UX = interface / experiência
OP = operação
AR = arquitetura / integração / dados

Tipo:
BLI = backlog inicial
COR = correção
AJU = ajuste
EVO = evolução

Tags auxiliares

HOT
PERF
SEC
MIG

Status possíveis

Pendente
Cancelado
Concluído
Esclarecido
Aguardando

Os identificadores formais são imutáveis e devem permanecer estáveis ao longo do tempo, mesmo que descrição, status ou classificação evoluam.

O documento situacao-atual.md representa a visão consolidada e vigente do backlog rastreável do projeto.

Exemplo de tabela em `situacao-atual.md`

ID                           | Descrição                                         | Tags        | Ata              | Origem               | Entrega      | Status
DEI-20260201-000-RF-BLI-0001 | Autenticação online por CPF e senha               |             | ata-20260101-001 | entendimento-inicial | leg-20260206 | Concluído
ESM-20260301-001-UX-AJU-0003 | Regra de habilitação do campo Tipo de Edificação  |             | ata-20260301-001 | esm-20260301-001     |              | Pendente
ESM-20260301-001-AR-EVO-0002 | Paginação da listagem de endereços                | MIG, PERF   | ata-20260301-001 | esm-20260301-001     |              | Pendente
ESM-20260220-004-OP-COR-0004 | Remoção de setor de agente em ambiente offline    | HOT         | ata-20260220-004 | esm-20260220-004     | leg-20260228 | Concluído

✦ Estado Operacional

O estado operacional do MEDE-CLI é armazenado no diretório:

.mede/

Este diretório contém:

fila de change-sets pendentes;
metadados da conversa ativa;
base SQLite local.

O diretório é efêmero e pode ser removido. O estado do projeto deve ser reconstruível a partir da documentação persistente.

✦ Configuração, Provedores de LLM e Ontologia Documental

O MEDE-CLI permite o uso de diferentes provedores de modelos de linguagem, configuráveis por projeto:

OpenAI
Anthropic
Ollama (modelos locais)
APIs compatíveis
modelos proprietários futuros

A configuração é realizada no arquivo:

mede.config.json

Ela permite:

seleção de modelo por fase metodológica;
operação offline;
controle de custos;
adequação a requisitos corporativos.

Internamente, o MEDE-CLI trabalha com tipos documentais estáveis.

O projeto pode configurar:

nomes de arquivos;
estrutura de diretórios;
prefixos documentais;
idioma dos documentos;
prompts metodológicos.

Essa abordagem desacopla a lógica da metodologia da representação física da documentação.

✦ Estrutura Documental Esperada

docs/
 ├── entendimento-inicial.md
 ├── readme.md
 ├── situacao-atual.md
 ├── requisitos-funcionais.md
 ├── requisitos-nao-funcionais.md
 ├── modelo-de-dados.md
 ├── cronograma.md
 ├── visao-e-escopo.md
 ├── atas-de-reuniao/
 ├── decisoes-arquiteturais/
 ├── especificacao-manutencao-sistema/
 └── log-entregas/

Nota: Os nomes das subpastas acima são os valores padrões e podem ser configurados no arquivo mede.config.json na propriedade directories.

✦ Exemplo de Uso (conceitual)

mede-cli cycle

mede-cli status

mede-cli pending

mede-cli approve

✦ Status do Projeto

O MEDE-CLI encontra-se em fase inicial de desenvolvimento.

Focos atuais:

engine de change-sets;
pipeline causal de evolução documental;
abstração de provedores de LLM;
reconstrução de estado do projeto;
experiência operacional via CLI.

✦ Roadmap Inicial

implementação funcional do comando cycle;
gerenciamento completo de change-sets;
reconstrução de estado a partir da documentação;
configuração multi-LLM;
suporte a modo offline;
plugin para VSCode;
interface gráfica futura.

✦ Visão

O MEDE-CLI é o primeiro passo para um novo paradigma de engenharia de software, no qual:

documentação evolui junto com o sistema;
decisões são preservadas como conhecimento estruturado;
LLMs operam sob governança metodológica;
geração de código e evolução documental convergem em um fluxo unificado de engenharia.

✦ Licença

Este projeto está licenciado sob a Apache License 2.0.

Consulte o arquivo LICENSE para mais detalhes.

✦ Contribuições

Contribuições são bem-vindas.

Antes de propor mudanças estruturais, recomenda-se compreender os princípios metodológicos da MEDE e o fluxo causal adotado pelo projeto.

mede-cli Release 1.1.1

Release 1.1.1 Toggle Dropdown 1.1.1 1.1.0 1.0.1 1.0.0

Documentation

MEDE-CLI

✦ Motivação

✦ Instalação

Requisitos

Instalação global (via npm)

Execução pontual (sem instalar)

A partir do código-fonte

Configuração de credenciais da LLM

Console interativo

Saída em JSON (para scripts)

✦ Publicações Relacionadas

✦ Conceito Central

✦ Princípios de Projeto

✦ Ciclo Metodológico

mede-cli cycle

Ordem do ciclo

Dependências entre etapas

Artefatos produzidos no ciclo

Regras de progressão

✦ Modelo Transacional do Ciclo

Comportamento por etapa

✦ Commit e Rollback

mede-cli commit

mede-cli rollback

✦ Comandos Disponíveis

mede-cli init

mede-cli cycle

mede-cli status

mede-cli refine

mede-cli approve

mede-cli reject

mede-cli pending

mede-cli apply

mede-cli discard

mede-cli files

mede-cli diff

mede-cli cat

mede-cli llm

mede-cli llm login

mede-cli llm logout

mede-cli llm test

mede-cli config

mede-cli config init

mede-cli config apply

✦ Semântica dos Níveis de Operação

✦ Convenções de Backlog, Situação Atual e Rastreabilidade

Padrão de identificação formal

Convenções

Tags auxiliares

Status possíveis

Exemplo de tabela em situacao-atual.md

✦ Estado Operacional

✦ Configuração, Provedores de LLM e Ontologia Documental

✦ Estrutura Documental Esperada

✦ Exemplo de Uso (conceitual)

✦ Status do Projeto

✦ Roadmap Inicial

✦ Visão

✦ Licença

✦ Contribuições

Stats

Releases

Contributors

mede-cli
Release 1.1.1

Release 1.1.1

1.1.1

1.1.0

1.0.1

1.0.0

`mede-cli cycle`

`mede-cli commit`

`mede-cli rollback`

`mede-cli init`

`mede-cli cycle`

`mede-cli status`

`mede-cli refine`

`mede-cli approve`

`mede-cli reject`

`mede-cli pending`

`mede-cli apply`

`mede-cli discard`

`mede-cli files`

`mede-cli diff`

`mede-cli cat`

`mede-cli llm`

`mede-cli llm login`

`mede-cli llm logout`

`mede-cli llm test`

`mede-cli config`

`mede-cli config init`

`mede-cli config apply`

Exemplo de tabela em `situacao-atual.md`