# Runbook — Applying the Protocol to a New Project Passo a passo operacional. Tempo estimado: **1 dia de preparação + 1 dia de execução por projeto de porte médio** (50–70 módulos), com a F3 paralela. --- ## 0. Pré-requisitos - [ ] O projeto está no workspace e **sobe** (ou tem um caminho para subir). - [ ] Acesso ao banco (para ler o registro de módulos) ou aos arquivos que o definem. - [ ] Acesso ao código-fonte em modo leitura. --- ## 1. Criar o diretório de dossiê do projeto ```bash cd mkdir -p dossie_modules/ ``` O `id` é o identificador curto do projeto: `portal-municipal`, `cms`, `sucesu-cms`, `tecvoto`. --- ## 2. Registrar o perfil em `projetos.json` Abra `dossie_modules/_protocolo/projetos.json` e acrescente a entrada: ```json "cms": { "titulo": "CMS", "descricao": "CMS moderno (Laravel 11, nwidart/laravel-modules)", "dos": "dossie_modules/cms", "versoes": { "atual": { "raiz": "cms" } }, "prefixos_codigo": ["cms"], "modulos": { "modelo": "pastas", "caminho": "cms/modules", "ignorar": ["Demo", "Blueprint"] }, "extras": {} } ``` | Campo | Significado | |---|---| | `dos` | Onde os dossiês deste projeto vivem | | `versoes` | Mapa `nome → {raiz}`; com duas versões, a comparação entre elas é automática | | `prefixos_codigo` | Prefixos de caminho que o auditor valida (`v5`, `v6`, `cms`, …) | | `modulos.modelo` | `registry` \| `pastas` \| `implicito` — ver [`04-DECISAO-MODULOS.md`](04-DECISAO-MODULOS.md) | | `modulos.comando` | Consulta que devolve o registro (modelo `registry`) | | `modulos.caminho` | Diretório das pastas (modelo `pastas`) | | `modulos.ignorar` | Pastas excluídas, com razão | | `alias` | Slug do registro → pasta do dossiê, quando divergem | | `extras` | Grupos adicionais (ex.: exclusivos de uma versão) | --- ## 3. F0 — Preparação ```bash # o projeto sobe? curl -sk -o /dev/null -w '%{http_code}\n' https://localhost:/ ``` Registre numa nota: versões do PHP/Laravel/banco, esquema de autenticação, localização das rotas, e **as premissas do pedido**, uma por linha. > Se o ambiente não sobe, **pare aqui**. Um dossiê de código que nunca rodou > carrega erro de leitura, e o erro se multiplica nos 9 arquivos. --- ## 4. F1 — Inventário ```bash python3 dossie_modules/_tools/inventario.py --projeto ``` Gera: - `dossie_modules//_00_panorama/10-INVENTARIO-DE-MODULOS.md` — a lista legível, com o modelo detectado e a evidência de cada item; - `dossie_modules//inventario.json` — o bruto, para as ferramentas. Confira o diff entre versões, se houver duas. --- ## 5. F2 — Decisão de módulos Abra o inventário gerado e aplique o critério: 1. Classifique cada item pela taxonomia (`registrado`, `exclusivo-`, `portal-only`, `sem-cms`, `infraestrutura`, `morto`). 2. Resolva divergências entre registro e código. 3. Registre alias (typos, duplicatas semânticas). 4. Escreva a razão de cada exclusão. 5. **Feche as lacunas de cobertura.** Rode o gate de cobertura e, para cada classe apontada, decida o destino: ```bash python3 dossie_modules/_tools/auditar.py --projeto | grep CODIGO ``` - Se a classe pertence a um módulo da lista → ela entra no dossiê desse módulo (destino: documentada). - Se ela é infraestrutura transversal, código morto ou duplicata de outra classe → registre em `projetos.json`, em `cobertura.lacunas`, com a razão: ```json "cobertura": { "lacunas": ["app/Http/Model/Prefecture/Entity.php"], "nota": "Infraestrutura transversal de endereco, usada por A Instituicao e Usuarios." } ``` O gate exige **destino**, não resolução. Lacuna sem destino reprova. Rode os testes **C1**–**C5** de [`04-DECISAO-MODULOS.md`](04-DECISAO-MODULOS.md) antes de seguir. --- ## 6. F3 — Dossiês ### 6.1 Criar as pastas ```bash for slug in $(jq -r '.modulos[] | select(.decisao=="documentar") | .slug' inventario.json); do python3 dossie_modules/_tools/scaffold.py --projeto --slug "$slug" --titulo "" done ``` ### 6.2 Despachar os agentes Para cada módulo, um agente com quatro blocos. **O bloco de contexto é compartilhado entre todos**; o resto é específico do módulo. ``` CONTEXTO (compartilhado) Objetivo do dossiê: especificação de reconstrução do em base moderna. Contrato: dossie_modules/_protocolo/03-CONTRATO.md (9 arquivos, cobertura obrigatória). Contexto da plataforma: . Regras: PT-BR, markdown, âncora arquivo:linha, código real, 100-400 linhas/arquivo. NÃO altere arquivos do projeto analisado. NÃO rode build/test no meio. TAREFA (por módulo) Módulo: — Pasta alvo: dossie_modules/// Arquivos de código a ler: Compare com a versão quando existir: ACEITE - 9 arquivos canônicos + extras indexados no 00-RESUMO.md - 100-400 linhas por arquivo - todo caminho citado existe - sem placeholder - mapa entre versões presente (se aplicável) - 00-RESUMO.md autossuficiente - 06-MIGRACAO-MODERNA.md permite escrever a migration nova sem abrir o legado ``` **Paralelize.** Despache em lotes; cada agente é uma fatia independente. Agentes que precisam de dado de outro módulo usam `write agent://`. **Não** peça build, lint ou teste no meio do voo — a verificação é da F6. --- ## 7. F4 — Consolidação Produza o `_00_panorama/` do projeto conforme a tabela em [`02-FASES.md`](02-FASES.md) §F4. As seções que **não** dependem de plataforma podem ser copiadas da estrutura do `_00_panorama/` do Portal Municipal, ajustando o conteúdo. --- ## 8. F5 — Defeitos 1. Colete os achados dos dossiês em um registro master (`_00_panorama/14-REGISTRO-DE-BUGS.md`). 2. Para cada candidato a **crítico**, reproduza. Use o roteiro abaixo. 3. Limpe e verifique o estado. ### Roteiro de sonda segura ```bash # 1. contar o estado ANTES docker exec psql -U -d -tAc \ "select count(*) from users" # 2. executar a sondagem (com token CSRF real, sessão real) # 3. contar o estado DEPOIS docker exec psql -U -d -tAc \ "select count(*) from users" # 4. reverter (atenção a soft delete e tabelas-pivot) docker exec psql -U -d -c \ "delete from role_users where user_id=" docker exec psql -U -d -c \ "delete from users where id=" # 5. RECONTAR — a contagem tem que voltar ao valor do passo 1 ``` > **Erro comum:** reverter pela aplicação deixa soft delete e linhas órfãs. > Reverta **por SQL**, e reconte. --- ## 9. F6 — Qualidade e índice ```bash python3 dossie_modules/_tools/gerar-readme.py --projeto python3 dossie_modules/_tools/auditar.py --projeto ``` Se aparecer problema, **corrija o dossiê**, não o gate — exceto quando o gate estiver errado, caso em que corrija o gate **e registre o caso novo** em `06-LICOES.md`. --- ## 10. Fechar - [ ] `auditar.py` → `OK`, código de saída 0. - [ ] `git status` limpo nos diretórios do projeto analisado. - [ ] Estado do banco no valor original (contagem). - [ ] `projetos.json` atualizado com o projeto. - [ ] `README.md` da raiz do dossiê lista o novo projeto. --- ## 11. Onde mexer quando algo não serve | Sintoma | Arquivo do protocolo | Arquivo da ferramenta | |---|---|---| | Novo tipo de defeito a catalogar | `05-CALIDADE.md` (tabela de gates) | `auditar.py` | | Novo formato de registro de módulos | `04-DECISAO-MODULOS.md` | `inventario.py` | | Novo item obrigatório no dossiê | `03-CONTRATO.md` | `_template/` | | Regra de estilo que falhou | `06-LICOES.md` | — | | Nova armadilha do protocolo | `06-LICOES.md` | — |