Roadmap em 5 fases

Veja em que ordem atacar as 27 tarefas do roadmap, do barato que alivia rápido ao padrão MCP que se expande para todos os apps. Cada fase tem marco e critério de saída.

A lógica da sequência#

1Fase 0estancar · 6 tarefas

→

2Fase 1fundação · 4 tarefas

→

3Fase 2contrato · 4 tarefas

→

4Fase 3decisões · 6 tarefas

→

5Fase 4padrão MCP · 7 tarefas

Primeiro estancamos o que sangra e custa pouco. Depois ligamos a fiscalização automática que sustenta todo o resto. Só então amarramos contratos e decidimos estrutura, do barato reversível ao caro irreversível. Por último, o padrão MCP leva a arquitetura dos adaptadores a todos os apps. Ficam fora 3 tarefas que já estavam feitas quando o roadmap foi montado: TB-13, TB-14, TB-15.

Fase 0
Estancar. Segredo, tokens vazados, container, systemd e docs quebradas.
Fase 1
Fundação executável. Lint, gates e cobertura ligados.
Fase 2
Contrato e dados. OpenAPI, erro padrão e env isolado.
Fase 3
Decisões estruturais. Topologia, workspace, Node e órfãos.
Fase 4
O padrão MCP da casa. Tools com envelope único, N+1 medido, Swagger e coordenadores.

O andamento por fase#

Quantas tarefas de cada fase já estão feitas, calculado do board:

Fase 0 — Estancar

0 de 6

Fase 1 — Fundação executável

2 de 4

Fase 2 — Contrato e dados

0 de 4

Fase 3 — Decisões estruturais

0 de 6

Fase 4 — O padrão MCP da casa

0 de 7

Fase 0 — Estancar#

Fechar os vazamentos que podem causar acidente ainda hoje, com custo baixo.

Por que nesta posição

Primeiro socorro: estanca o sangramento antes de operar.

As tarefas desta fase são:

Tarefa	Apps	Esforço	Estado
`TB-03` Corrigir a documentação quebrada e criar os READMEs que faltam	`conta-central` `load-balance` `render` `motor` `agent-package`	barato	a fazer
`TB-04` Instalar a varredura de segredo e o Renovate na raiz do monorepo	`spaceAI` `agent-package` `render`	barato	a fazer
`TB-05` Pôr as três fechaduras nos containers do load-balance, do mypanel e do motor	`load-balance` `mypanel` `motor`	barato	a fazer
`TB-06` Unificar o pin do `@nomad/ui` e padronizar os paths de health	`conta-central` `load-balance` `motor` `mypanel`	barato	a fazer
`TB-17` Corrigir o `WorkingDirectory` do systemd de `/be` para `/backend`	`motor`	barato	a fazer
`TB-29` Rotacionar os dois tokens que ficaram no histórico do `.mcp.json`	`spaceAI` `agent-package` `mypanel`	barato	a fazer

Marco: Varredura de segredo na raiz, containers com as três fechaduras, units do systemd apontando para /backend e os tokens antigos do .mcp.json revogados.

Critério de saída: Nenhum segredo novo entra sem varredura e nenhum container novo sobe sem as fechaduras.

Fase 1 — Fundação executável#

Ligar a fiscalização que trabalha sozinha a cada verificação local.

Por que nesta posição

Radar ligado: a fiscalização passa a multar sozinha, sem depender de revisão humana.

As tarefas desta fase são:

Tarefa	Apps	Esforço	Estado
`TB-01` Instalar ESLint com regra de fronteira nos 3 backends sem lint	`load-balance` `motor` `mypanel`	barato	feito
`TB-30` Tirar o `eval` do logger do load-balance	`load-balance`	barato	feito
`TB-09` Adotar piso de cobertura e `knip` nos 4 projetos sem	`conta-central` `load-balance` `motor` `mypanel`	médio	a fazer
`TB-16` Rodar `npm run gates` no motor com instalação limpa	`motor`	médio	a fazer

Marco: ESLint de fronteira nos backends que não tinham lint, gates do motor verde com instalação limpa e piso de cobertura rodando local, via npm run gates.

Critério de saída: Lint, testes e build verdes no load-balance, no motor e no mypanel, com o output colado na mensagem de merge, antes de qualquer tarefa da Fase 2.

Fase 2 — Contrato e dados#

Amarrar frontend e backend no mesmo contrato, como um trabalho de data quality.

Por que nesta posição

Cardápio impresso: um cardápio oficial acaba com as cópias à mão dos garçons.

As tarefas desta fase são:

Tarefa	Apps	Esforço	Estado
`TB-02` Fechar o cliente OpenAPI gerado no render	`render`	barato	a fazer
`TB-07` Isolar o `process.env` em `src/config` e gerar o `.env.example` do schema	`load-balance` `motor` `mypanel` `conta-central`	médio	a fazer
`TB-08` Adotar a RFC 9457 como envelope de erro único dos 6 backends	`conta-central` `mypanel` `load-balance` `motor`	médio	a fazer
`TB-11` Gerar o contrato REST nos projetos com catálogo manual	`motor` `conta-central` `load-balance` `mypanel`	alto	a fazer

Marco: Cliente OpenAPI gerado, erro padrão RFC 9457 e variáveis validadas num módulo único.

Critério de saída: Nenhuma rota nova sem cliente gerado e nenhum erro fora do envelope padrão.

Fase 3 — Decisões estruturais#

Decidir por escrito o que trava todas as outras obras.

Por que nesta posição

Escritura registrada: decide uma vez, e ninguém reabre o debate.

As tarefas desta fase são:

Tarefa	Apps	Esforço	Estado
`TB-10` Decidir a topologia do repositório por escrito e reduzir os lockfiles	`motor` `mypanel`	médio	a fazer
`TB-12` Padronizar features por domínio e a fonte de verdade do design system	`conta-central` `render` `mypanel` `motor`	médio	a fazer
`TB-18` Decidir o destino do `Dockerfile.worker` órfão	`motor`	barato	a decidir
`TB-19` Decidir o rename do pacote `motor-fe`	`motor`	barato	a decidir
`TB-20` Decidir se o `nomad-ui` vira workspace ou segue remoto	`spaceAI`	médio	a decidir
`TB-21` Alinhar o Node 22 do motor com o Node 24 da casa	`motor`	alto	a decidir

Marco: Topologia, workspace do nomad-ui, versão do Node e Dockerfile órfão decididos, com as exceções explícitas.

Critério de saída: Cada decisão vira registro escrito; sem registro, a tarefa não fecha.

Fase 4 — O padrão MCP da casa#

Fechar a arquitetura dos adaptadores: uma regra de negócio, duas portas de entrada.

Por que nesta posição

Um balcão com duas janelas: o mesmo atendente atende pela HTTP e pelo MCP, sem dois atendentes aprendendo a mesma coisa.

As tarefas desta fase são:

Tarefa	Apps	Esforço	Estado
`TB-22` Dar versão e envelope único às tools MCP do agent-package	`agent-package` `render`	médio	a fazer
`TB-23` Medir o N+1 por tool e padronizar a paginação	`agent-package` `render` `mypanel` `motor` `load-balance` `conta-central`	médio	a fazer
`TB-24` Desacoplar o núcleo dos services do `mcp/` no agent-package	`agent-package`	médio	a fazer
`TB-25` Escrever o system prompt e a doc de tools de cada agente coordenador	`agent-package` `motor` `render` `mypanel` `load-balance` `conta-central`	médio	a fazer
`TB-26` Levar o Swagger aos 4 backends que ainda não têm	`conta-central` `load-balance` `motor` `mypanel`	médio	a fazer
`TB-27` Fechar as 134 operações sem contrato no agent-package	`agent-package`	alto	a fazer
`TB-28` Levar o padrão de serviço com dois adaptadores aos outros 4 apps	`motor` `load-balance` `render` `conta-central`	alto	a fazer

Marco: Tool com envelope único e versão própria, N+1 medido por tool, Swagger em todo backend e o coordenador de cada app com prompt e doc de tools.

Critério de saída: Toda tool nova sai de um ponto só, responde no envelope padrão, tem o custo de query declarado, e o Swagger de cada backend descreve a operação inteira.