O artefato Control é o painel vivo de status do projeto. Ele serve como log de navio documentando verdades operacionais: os bloqueios reais, atrasos, mudança de alinhamento estratégico, bugs reportados em produção que impactam nas tasks, e o farol diário de quem está tocando e supervisionando.
Fase: 7 — Governança Contínua (Status)
Pré-requisito: Docs/tasks.md rodando no dia-a-dia.
Template: Templates/Full/control.md ou Templates/Quick/control.md
Artefato oficial: Docs/control.md
Quando criar ou revisar
- Ao desdobrar o
Docs/tasks.md(criação base). - Imediatamente após uma Task vital ter esbarrado num bloqueio não-solucionável no mesmo commit.
- Semanalmente / diariamente (Scrum ou Async Update) para atestar que os riscos previamente mapeados estão sumindo.
- Quando a diretoria ou o PM precisa mudar o rumo das prioridades sem quebrar o rastro do passado das decisões.
Full vs Quick
| Situação | Template |
|---|---|
| Repositório multiequipes (Front, Back, DevOps) gerindo entregas paralelas pesadas | Templates/Full/control.md |
| Automação restrita entre AI e seu autor numa CLI sem bloqueios humanos cruzados | Templates/Quick/control.md |
| Se a AI esbarrou em bloqueios crônicos não contornáveis na mesma sprint | Mover para Full para detalhar Bloqueios e Riscos (Seções 9 e 13) |
Estrutura — Control Full
O modelo Full espelha todas as 17 seções rigorosas do painel original do framework. Elas nunca devem ser comprimidas.
1. Identificação
Nome do projeto:
Versão do documento:
Status geral do projeto: [não iniciado / em andamento / bloqueado / estabilização / concluído / pausado]
Documentos base: Docs/plan.md, Docs/tasks.md, Docs/deploy.md
Data de criação:
Última atualização:2. Objetivo do Documento
Cobre:
- Status atual, andamento por fase, módulo, tarefas em destaque, bloqueios crônicos diários, desvios mapeáveis e riscos operacionais ativos do projeto real.
Não cobre:
- Implementação detalhada, contratos de subida de api e status atômicos que caberiam num simples
git logde tasks diárias.
3. Regra de Marcação
A sintaxe canônica a ser operada neste painel descritivo de texto:
- ( ) não concluído
- (x) concluído
Status textuais complementares vigentes neste documento:
- em andamento
- bloqueado
- aguardando
- revisão
- validado4. Estado Geral do Projeto
O sumário executivo em poucas linhas, para leitura rápida de gestores e AIs de monitoria:
Resumo executivo do estado atual: Fase estrutural concluída, módulo frontend bloqueado por dependência CORS.
Situação atual: bloqueado.
Saúde geral do projeto: [boa / atenção / crítica]5. Status por Fase
### FASE 01 — Fundação Estrutural
- Status: [concluída]
- Progresso percebido: [concluído]
Checklist da fase:
- (x) Setup Typescript
Bloqueios da fase: [nenhum]
### FASE 02 — Base Funcional
- Status: [em andamento]
- Progresso percebido: [baixo / médio / alto / concluído]6. Status por Milestone
Valida se as super-fases marcadas com release real prosperaram:
### M1 — Alpha Funcional
- Status: [em andamento]
Condições de conclusão:
- (x) Deploy no staging funcionando sem erro de 500
- ( ) App mobile enviada à TestFlight7. Status por Módulo
O mapeamento da especialidade:
### MÓDULO: Autenticação
- Status: [bloqueado]
- Fase atual: [FASE-02]
- Milestone relacionado: [M1]
Tasks críticas relacionadas:
- TASK-003 — Conexão Clerk Auth
Bloqueios: Ausência da chave JWT oficial de sandbox.8. Tasks Críticas em Acompanhamento
Destaque apenas do que trava ou machuca o cronograma geral das Sprints:
### TASK-003 — Setup Auth
- Status: [bloqueada]
- Módulo: [Autenticação]
Pendências principais:
- Chave vazou no commit x, precisamos rolar e emitir uma nova Key antes da volta ao staging.
Última movimentação relevante: [Dev Backend A notificou a subida da request X no dia Z]9. Bloqueios Ativos
Bloqueios travam frentes de dev ou tasks:
### BL-001 — Bloqueio de Política CORS
Status: ativo
Descrição: API de terceiros rejeitando a conexão no ambiente de Staging / Localhost.
Impacto: alta
Afeta: FASE-02, TASK-012
Ação necessária: Solicitar whitelist de IP ao fornecedor.
Responsável ou origem: Equipe parceira.10. Decisões Tomadas
As atas logadas de mudanças estratégicas decididas. Ninguém chuta porque o plano desviou no meio se ele for documentado:
### DEC-001 — Mudança do BD relacional
Data: 10/11/2026
Decisão: Abandono do PostgreSQL pelo SQLite na Fase 1.
Motivo: Evitar infra externa enquanto validamos o fluxo MVP.
Impacto: O Docs/ architecture.md e o deploy.md sofrem rewrite para alinhar a mudança.
Documentos afetados: architecture, deploy.11. Desvios em Relação ao Plano
Mudanças de prioridade: Foco na área de Checkout subiu na frente do Painel de Leads.
Docs/plan.md precisa ser revisado? [sim]12. Validações Realizadas
Atendem o processo de testes estabelecido (Quality Gate contínuo):
### Validação de contrato
- (x) Endpoints CRUD Users respondem status <200> conforme YAML
### Validação de deploy
- ( ) Deploy automatizado via Main
### Validação final Dev e AI
- ( ) realizada13. Riscos Ativos
Qualquer situação iminente crônica:
### RK-001 — Faturamento de Vercel com DDoS
Status: monitorando
Descrição: Tráfego alto em páginas CSR.
Impacto: médio | Probabilidade: baixa
Mitigação em curso: Adicionada Cloudflare no apontamento e rate_limit ao nginx.14. Próximos Passos
Os vetores de direcionamento prioritários reais do Dia Seguinte:
Próximas ações imediatas:
- Contornar BL-001 e aprovar PR bloqueado.
Próximas tasks críticas:
- TASK-004 e TASK-00815. Histórico de Atualizações
Registro de mudanças da própria leitura do doc control.
### 11/11/2026
- Atualização do status executivo de Boa para Atenção.
- Inserido risco RK-001 após instabilidades.16. Diretrizes de Uso
Pilar inalienável deste doc:
- O painel baseia-se na VERDADE dolorosa, e não na promessa futurista. Se tá sujo de erro técnico nas tasks diárias, está bloqueado aqui.
- Omitir risco porque acha inconveniente destrói toda a razão do Controle.17. Síntese Operacional para Dev e AI
Para desenvolvedores logando atividade diária:
O Control responde ao Status Diário/Semanal. Se você fechou o milestone 1 no `tasks.md`, é OBRIGATÓRIO vir aqui fechar atestar o Checklist (Seções 6 e 12).Prompt para gerar com agente
Atue como GovernanceAgent.
Objetivo: Transformar status implícitos das tasks e do plano em Logs visíveis do Docs/control.md
Contexto base:
- Docs/plan.md
- Docs/tasks.md
- Templates/Full/control.md
Leia os artefatos base informados e extraia os blocos que demonstram quais etapas das Fases reais encontram-se concluídas (baseadas no status 'x' do plano de tasks).
Popule obrigatoriamente as seções de 1 a 17, explicitamente com os dados retirados atestando se o projeto está fluindo ou gerido sob bloqueio.
Liste em Seção 8 os maiores gargalos abertos nas TASKS atuais identificadas.Definição de pronto
O acompanhamento de Control tem qualidade mínima garantida quando:
- Todas as 17 seções, da Identificação principal até a Síntese, constam perfeitamente sem aglutinar pedaços diferentes.
- A Seção 4 reflete a vida real e atual de Saúde (Boa/Atenção/Crítica) coerente aos bloqueios da seção 9.
- Seções "Decisões Tomadas e Desvios" refletem os recálculos vitais, garantindo registro na Ata (seções 10 e 11).
- O Histórico de Atualizações (seção 15) mantém rastro visível do andamento dos Checks operacionais.
Atenção
Entender control.md como "promessa" em vez de "diagnóstico diário de radiografia". Um painel verde brilhante quando o CI quebrou metade do deploy prova que ninguém monitorou o Control ou atrelou uma falha verídica ao Bloqueio!
Erros comuns
| Erro | Correção |
|---|---|
| Esquecer de registrar Desvios (Seção 11) | Prioridade de Produto mudou, o time alterou a FASE, mas não atualizou o plan porque ninguém no control.md acusou o desvio de rota. Perca de rastreio fatal. |
| Esconder riscos técnicos (Seção 13) | Achismo que infra gargalou, mas não registrar "pois parece simples" engole dias úteis investigando no "Escuro". Registre RKs sempre. |
| Fundir tarefas comuns em Tasks Críticas | Tarefas cotidianas (Seção 8 não trata perfumaria) ficam lá no Tasks. O controle dita TASKS IMPORTANTES, fundadoras e vitais. |
| Omitir Histórico e Validações | Control se dá como "pronto final" e "Aprovado DevAI" (seções 12 e 15 testadas). Marcar x com testes em erro macula a base do repositório. |
Relação com outros artefatos
Docs/tasks.md — Executa cada folha no nível microscópio por commits diários.
↓
Docs/control.md — Analisa a cadeia de folhinhas (tasks), relata doenças da raiz (RK/BLs bloqueantes) e consolida a visão.