Como a casa trabalha

Saiba como verificar uma mudança sem CI, o que todo container precisa ter, onde cada contrato está escrito e como mudar esta documentação.

A casa em 30 segundos#

Seis apps moram num diretório só para a IA trabalhar com um contexto único. Cada app continua sendo dela: banco, container e deploy próprios. A versão completa, com o inventário e a costura, está em A casa.

A regra é de deploy e de código, não de isolamento total. Os backends autenticam contra o conta-central, e o motor chama o load-balance a cada chamada de LLM. Dependência de rede explícita não quebra a regra; dependência de código-fonte, sim.

Verificar sem CI#

Nenhum app tem pasta .github. Não é esquecimento: é decisão do dono, registrada no AGENTS.md. A verificação roda na máquina de quem codou, e o resultado vai colado na mensagem de merge, como o check de data quality que roda antes de publicar o dashboard.

Para passar pelo gates, você precisa de:

• Dependências do zero: npm ci no app que você tocou.
• O agregador: npm run gates na raiz do app. Hoje só o motor e o frontend do load-balance têm um; nos outros, rode os scripts do pacote (lint, typecheck, test e build).
• O registro: o output colado na mensagem de merge.

Sem node_modules instalado, diga que não rodou, em vez de afirmar que passou.

As três fechaduras de todo container#

Todo container de produção precisa das três. A tabela mostra por que cada uma existe e quem já tem:

O load-balance e o mypanel ainda não têm nenhuma das três: é a TB-05. Uma quarta regra vale para todos: segredo entra por env em runtime, nunca por ARG ou ENV de build.

Onde os contratos estão escritos#

Apps conversam por contrato HTTP versionado, nunca por import e nunca por banco compartilhado. E contrato aqui não é aperto de mão: é documento no repositório, que o código cita pelo nome. As costuras que já existem são estas:

Se o contrato muda, o documento muda no mesmo PR. Mudança que atravessa apps é mudança de contrato, e isso vale para a TB-08 (envelope de erro) e para a TB-11 (contrato REST gerado).

Como entra um app novo#

Para adicionar um app à casa, siga estes passos:

1. Crie backend e frontend

   Pastas backend/ e frontend/, cada uma com o seu package.json e o seu lock.

2. Escreva um Dockerfile por processo

   Já com as três fechaduras: USER, HEALTHCHECK e base com digest.

3. Documente só os nomes das variáveis

   O .env.example lista nomes. O valor fica no .env, nunca no git.

4. Escreva o contrato

   Toda conversa com outro app vira documento em <app>/docs/, citado pelo código.

5. Entre no gates

   O pacote novo participa do agregador. Sem gates, não há verificação.

6. Registre no inventário

   Adicione a linha do app na tabela do AGENTS.md.

Como a IA trabalha neste repo#

O monorepo existe para a IA trabalhar com contexto. Por isso, valem cinco regras:

1. Leia o contexto antes de mexer. O <app>/CLAUDE.md do app, quando existir (hoje só o motor tem), e o contrato dos apps com quem ele conversa. Usar o que está escrito é mais barato e mais seguro que inferir do código.
2. Mudança que atravessa apps é mudança de contrato. O documento muda no mesmo diff, e o código passa a citá-lo.
3. Não alinhe o app vizinho por conta própria. Padrão diferente no app ao lado é divergência conhecida, medida na auditoria. Ela se corrige por decisão, num PR próprio, não como efeito colateral de outra tarefa.
4. Rode os gates do app que você tocou. Sem node_modules, diga que não rodou.
5. Conte o que mudou em outro app. Se a tarefa era num app e tocou outro, pare e pergunte, ou registre como decisão explícita.

Antes de dar uma tarefa por concluída#

Uma tarefa só vai para a coluna Feito do board quando passa por estes portões:

• npm run gates passa, ou o equivalente do app onde ainda não há agregador.
• Migration nova é versionada: nada de db push fora de banco descartável.
• Nenhum import entre apps foi introduzido.
• Contrato alterado tem o documento de contrato alterado no mesmo PR.
• Segredo novo tem só o nome no .env.example, o valor fora do git e o gitleaks passando (a varredura ainda não está instalada no monorepo: é a TB-04).

Depois, mude o estado da tarefa neste guia e cite a evidência, como mostra a próxima seção.

Como alterar esta documentação#

O portal é a fonte única da documentação: HTML estático gerado por Python, sem framework, sem CDN e sem dependência. O guia de tarefas mora dentro dele e usa o mesmo chrome e o mesmo CSS. Nenhum .html se edita à mão, porque ele é saída do build.

Cada tipo de mudança tem um lugar:

O guia importa o chrome e a navegação do build.py do portal. Mudou um componente ou a sidebar de lá? Rode os dois builds. Para publicar uma mudança no guia, siga estes passos:

1. Edite a fonte

   Tarefa é uma tupla em TASKS: id, título, descrição, apps, esforço, impacto, estado, origem e evidência. O estado é fazer, decidir ou feito, e a evidência é caminho real no disco, relativo à raiz do repositório.

2. Regenere as páginas

   Rode o build do guia dentro de tarefas/:

   copiar

   bash

   cd documentation-portal/tarefas
   python3 build.py

   O build lista as páginas e o resultado da conferência das fontes:

   textexit 0

   OK 5 páginas geradas em tarefas/:
      index.html
      visao-geral.html
      auditoria.html
      board.html
      roadmap.html
   Conferência das fontes: 0 avisos.

3. Confira os números

   Nenhum número do guia se digita. As contagens do board, das fases e de cada app saem de TASKS e ROADMAP, e os scores saem da lista APPS do portal. O build avisa se uma evidência não existe no disco, se uma tarefa aberta está fora do roadmap ou se um score diverge da AUDITORIA-ALINHAMENTO.md.

4. Veja no navegador

   Abra o index.html direto, ou sirva a pasta do portal:

   copiar

   bash

   cd documentation-portal
   node server.js 4173