# As 7 Fases do Protocolo

Cada fase tem **entrada**, **ação**, **saída** e **gate**. O gate é objetivo:
se não for verificável por máquina ou por contagem, não é gate — é opinião.

> **Regra de ouro:** uma fase não começa sem a saída da anterior **verificada**.
> Em particular, nenhum dossiê de módulo é escrito antes de o inventário
> existir (F1→F2→F3).

---

## F0 — Preparação

**Objetivo.** Saber com o que se está trabalhando antes de olhar código.

### Entrada
- O pedido (com as premissas que o pedido carrega).
- O workspace.

### Ação
1. **Identificar a unidade de análise.** Um projeto? Duas versões do mesmo
   projeto? Um monorepo? Registrar a decisão e a razão.
2. **Mapear o terreno:** estrutura de diretórios, `composer.json`
   (framework e versão de PHP), `package.json`, esquema de banco, serviços
   externos (filas, cache, storage).
3. **Registrar as premissas do pedido** em uma lista verificável. Cada uma
   recebe um destino na F4/F5: *confirmada* ou *divergente*.
4. **Subir o ambiente.** Registrar URL, porta, credencial de teste e o
   comando exato. Se não sobe, parar aqui e resolver — um dossiê de código
   que nunca rodou carrega erro de leitura.
5. **Localizar o registro de módulos** (ver
   [`04-DECISAO-MODULOS.md`](04-DECISAO-MODULOS.md)). É a decisão mais
   importante da F0: ela define o escopo de tudo.
6. **Registrar o perfil do projeto** em `projetos.json`.

### Saída
- `projetos.json` com a entrada do projeto.
- Nota de preparação: versões, stack, como subir, premissas.

### Gate
- Ambiente responde HTTP com código de sucesso.
- O registro de módulos foi localizado **e lido** (não apenas deduzido).
- As premissas estão listadas, uma por linha, com um marcador de destino.

---

## F1 — Inventário mecânico

**Objetivo.** Produzir, sem julgamento, a lista completa do que existe.

### Entrada
- Perfil do projeto (F0).

### Ação
1. Rodar `inventario.py`:
   ```bash
   python3 dossie_modules/_tools/inventario.py --projeto <id>
   ```
   A ferramenta extrai, por versão do projeto:
   - controllers (caminho → classe → ações públicas);
   - models (caminho → classe → tabela, quando dedutível);
   - migrations (arquivo → operação → tabela);
   - routes (arquivo → contagem e nomes);
   - views (templates Blade por diretório);
   - testes (arquivos de teste por área);
   - **o registro de módulos**, no modelo que o projeto usar.
2. O inventário **classifica** cada item com a evidência que o вклюuiu.
3. Se houver mais de uma versão (ex.: v5 e v6), produzir o **diff**:
   controllers só em A, só em B; models; migrations; e o conjunto de
   módulos exclusivo de cada versão.

### Saída
- `inventario.json` (bruto, para as ferramentas).
- `10-INVENTARIO-DE-MODULOS.md` (legível, para o humano).

### Gate
- Todo controller, model e migration está classificado.
- O diff entre versões está completo (nenhum item sem o rótulo
  "em ambas" / "só em A" / "só em B").
- Nenhum item marcado com evidência vazia.

---

## F2 — Decisão de módulos

**Objetivo.** Fixar a lista canônica: o que é um módulo, neste projeto.

### Entrada
- Inventário (F1).
- Critério de [`04-DECISAO-MODULOS.md`](04-DECISAO-MODULOS.md).

### Ação
1. Aplicar o critério. Para o modelo **baseado em registro** (o caso do
   Portal Municipal): a lista vem da tabela/seed, e o inventário serve para
   *completar* (módulos órfãos no código que não estão no registro) e para
   *explicar* (módulos do registro sem código).
2. Classificar cada módulo pela **taxonomia**:
   - `registrado` — tem entrada no registro oficial;
   - `exclusivo-<versão>` — existe só numa versão;
   - `portal-only` — só superfície pública, sem backoffice;
   - `infraestrutura` — transversal (log, config, menu, permissões);
   - `sem-cms` — código de negócio sem backoffice.
3. Produzir o **mapa de cobertura**: cada diretório de código relevante
   (controllers, models, migrations) tem um módulo dono; cada módulo tem
   pelo menos um artefato de código.
4. Registrar as **decisões de escopo** com razão — é aqui que se decide se
   um item entra ou não, e o porquê fica escrito.

### Saída
- Seção "módulos" do `10-INVENTARIO-DE-MODULOS.md` com a taxonomia aplicada.
- Mapa de cobertura: código → módulo.

### Gate
- Nenhum diretório de código sem dono.
- Nenhum módulo sem artefato de código (salvo decisão registrada).
- Toda decisão de exclusão tem razão escrita.

---

## F3 — Dossiês (paralelo)

**Objetivo.** Produzir os 9 documentos por módulo, com o mesmo padrão.

### Entrada
- Lista canônica (F2).
- Contrato ([`03-CONTRATO.md`](03-CONTRATO.md)) e
  [`../_template/`](../_template/).

### Ação
1. Criar as pastas:
   ```bash
   python3 dossie_modules/_tools/scaffold.py --projeto <id> --slug <slug> --titulo "<Título>"
   ```
2. Despachar **um agente por módulo**, em paralelo, com fatia auto-contida:
   - **contexto compartilhado**: objetivo do dossiê, stack, convenções;
   - **contrato**: o que cada um dos 9 arquivos cobre;
   - **alvo**: a pasta e os arquivos de código que o agente pode ler;
   - **aceite**: resultado observável, ex.: "os 9 arquivos existem, cada
     caminho citado existe, o mapa v5→v6 está presente".
3. Os agentes **não** rodam build, lint ou teste no meio do voo — a verificação
   é da F6, em uma única rodada.
4. Agentes que precisem de um dado de outro módulo usam
   `write agent://<id>` em vez de esperar.

### Saída
- `<slug>/00-RESUMO.md` … `<slug>/08-GAPS-E-DIVIDAS.md` (+ extras).

### Gate
- Os 9 arquivos canônicos existem em cada pasta.
- Cada arquivo tem 100–400 linhas.
- Todo caminho citado existe.
- Nenhum placeholder.
- O mapa de versões (quando aplicável) está presente.

---

## F4 — Consolidação de plataforma

**Objetivo.** O que é comum a todos os módulos.

### Entrada
- Dossiês (F3).

### Ação
Produzir o `_00_panorama/` com, no mínimo:

| Documento | Conteúdo |
|---|---|
| `00-RESUMO.md` | Visão geral e índice do panorama |
| `01-ARQUITETURA.md` | Stack, camadas, diagrama, ciclo de requisição |
| `02-MODELAGEM.md` | Mapa de todos os bancos e domínios |
| `03-ROTAS.md` | Mapa de rotas por superfície (CMS, portal, API) |
| `04-MIGRACAO.md` | Estratégia de reconstrução, ordem, critérios |
| `05-DIVIDA-TECNICA.md` | Padrões de debt agregados |
| `09-SEGURANCA.md` | Achados de segurança com evidência |
| `10-INVENTARIO-DE-MODULOS.md` | A lista canônica (F1+F2) |
| `12-PLANO-DE-MIGRACAO.md` | Onde cada módulo entra na v7 |
| `13-BACKLOG.md` | Backlog priorizado derivado dos dossiês |
| `14-REGISTRO-DE-BUGS.md` | O registro master de defeitos |

### Saída
- `_00_panorama/` completo.

### Gate
- Toda referência cruzada do panorama resolve para um módulo real.
- O inventário do panorama bate com a lista canônica da F2.
- As premissas do pedido (F0) têm destino: confirmadas ou divergentes.

---

## F5 — Defeitos: leitura e execução

**Objetivo.** Registrar defeitos com severidade honesta.

### Entrada
- Dossiês (F3) e panorama (F4).
- Ambiente em execução (F0).

### Ação
1. **Coleta por leitura:** cada dossiê contributes achados para o registro
   master, com `arquivo:linha` obrigatório.
2. **Classificação** por categoria (segurança, dados, funcional, qualidade,
   performance) e severidade (crítica, alta, média, baixa).
3. **Verificação em runtime dos críticos.** Para cada candidato a crítico:
   - reproduzir com requisição/consulta concreta;
   - registrar o resultado (saída observada);
   - **rebaixar** o que não se reproduzir.
4. **Caderno de sondas.** Cada teste registra: objetivo, conta de estado
   antes, comando, saída, conta de estado depois.
5. **Limpeza e verificação** (P4). Recontar o que foi alterado e conferir.
6. **Backlog priorizado:** esforço × risco × dependência, com ordem de
   execução e o que desbloqueia.

### Saída
- Registro de defeitos (tabela-resumo + detalhamento item a item).
- Backlog priorizado.
- Relatórios de segurança dedicated.

### Gate
- Todo crítico tem prova de execução registrada, **ou** foi rebaixado com
  a razão escrita.
- O ambiente está no estado original — verificado por contagem.
- Todo defeito tem `arquivo:linha`.

---

## F6 — Qualidade e índice

**Objetivo.** Fechar com verificação automática.

### Entrada
- Tudo o que veio antes.

### Ação
```bash
python3 dossie_modules/_tools/auditar.py      --projeto <id>   # gate
python3 dossie_modules/_tools/gerar-readme.py  --projeto <id>   # índice
python3 dossie_modules/_tools/auditar.py      --projeto <id>   # revalida
```

### Saída
- `README.md` gerado.
- Saída de auditoria sem problemas.

### Gate
- `auditar.py` → `OK — nenhum problema encontrado` e código de saída 0.
- `README.md` coerente com o disco (contagens e listas).

---

## Cronograma de referência

A execução real do Portal Municipal (66 módulos) consumiu aproximadamente:

| Fase | Esforço | Observação |
|---|---|---|
| F0 | ~1 h | Incluiu subir instâncias e mapear o registro |
| F1+F2 | ~1 h | Ferramenta + decisão de taxonomia |
| F3 | ~10 h | Paralelo: 1 agente por módulo, ~8–12 min cada |
| F4 | ~3 h | Consolidação de plataforma |
| F5 | ~4 h | Incluiu as sondas em runtime |
| F6 | ~15 min | Ferramentas |

> **F3 é o gargalo e é inerentemente paralelo.** A alavanca é a fatia
> auto-contida (P8) e o contrato fixo: sem eles, cada agente reconstrói as
> convenções e o tempo por módulo triplica.