---
id: REIMPL-CEGAS
tipo: reimplementacao
onda: 5
status: concluido
unidades: []
fontes:
  - V2/
  - app/
  - config/
depende_de: [REIMPL-ORDEM, REIMPL-PARIDADE, REIMPL-RISCOS]
consumidores: [coordenacao-do-corpus, qa, agente-reconstrucao-cega]
criticidade: alta
dono: agente-reimplementacao
---

## Efeito

Descreve o protocolo de três **reconstruções cegas** exigidas pelo gate G5
(`PLANO.md:321`). O efeito é medir se o corpus, sozinho, permite reconstruir schema,
rotas e telas — e transformar cada divergência em correção de documento, não em
“conhecimento tribal” de quem viu o código.

Este documento **não executa** os exercícios. Ele fixa: unidades, ambiente, entradas,
saídas, critérios de comparação, limiares e o ciclo de correção.

## Abordagem

### 1. Desenho do experimento

| Exercício | Unidade | Tamanho | Por que ela |
|---|---|---|---|
| **C1** | `MOD-INFRAESTRUTURA-MAILAUDIT` | 5 arquivos, 11 PCs, 2 rotas, 2 blades (`05_modulos/Infraestrutura/MailAudit/spec.md:639-649`) | unidade pequena e somente-leitura; testa se o corpus distingue “listar” de “escrever” e se documenta o detalhe que só abre o registro mais recente |
| **C2** | `MOD-INFRAESTRUTURA-FEEDRSS` | 4 arquivos, 11 PCs, 3 rotas, 1 blade (`05_modulos/Infraestrutura/FeedRss/spec.md:677-687`) | módulo de UI sobre um serviço; testa separação de responsabilidade, autorização por identidade e efeito de cache |
| **C3** | `MOD-PUBLICACOES-AGENDA` | 14 arquivos, 42 PCs, 6 rotas CMS + 2 públicas (`05_modulos/Publicacoes/Agenda/spec.md:700-719`; `_indices/rotas.csv`) | tamanho médio com CMS e portal, dois critérios de publicação e integração com busca/feed |

A ordem é crescente em dificuldade. C1 e C2 podem rodar em paralelo; C3 só depois que o
protocolo estiver calibrado por eles.

### 2. Isolamento

O agente da reconstrução cega recebe:

- uma cópia somente-leitura de `sucesu_analise/` (todo o corpus, inclusive `_indices/`,
  `_qa/` e este documento);
- um diretório de trabalho vazio para os artefatos;
- acesso a nenhum checkout de `sucesu-cms/`, nenhum histórico de sessão, nenhum
  `REFERENCE/`, nenhuma internet.

Não recebe: nome do exercício anterior, resposta de outro agente, lista de divergências,
nem os documentos de revisão como “gabarito”. O agente pode ler `_qa/` como parte do
corpus; o que não pode é receber a comparação pronta.

Regras de conduta:

1. Toda afirmação produzida deve citar `caminho:linha` ou índice do corpus.
2. O que não estiver no corpus vira `[I]` (inferência) ou `[L]` (lacuna), nunca invenção
   silenciosa.
3. O agente não pode “corrigir” o corpus; só registrar a dúvida.
4. O resultado é congelado com hash antes da comparação.

### 3. Artefatos exigidos do agente cego

| Artefato | Formato | Conteúdo mínimo |
|---|---|---|
| `schema.sql` | DDL | tabelas, colunas, tipos, PK, FK, unique, índices, soft delete, defaults |
| `rotas.csv` | CSV com o cabeçalho de `_indices/rotas.csv` | método, URI, nome, middleware, controller, ação, permissão, auth, throttle, cache, request, resposta, efeito, fonte |
| `telas.md` | Markdown | por tela: rota, view, props, DOM ids, eventos JS, estados vazio/erro, ações |
| `servicos.md` | Markdown | assinatura pública, efeitos, erros, idempotência, consumidores |
| `pcs.md` | Checklist | para cada PC da unidade: passa / falha / não determinável, com a evidência usada |
| `duvidas.md` | Lista | toda lacuna encontrada e onde o corpus deveria tê-la |

Para C3, acrescentar `portal.md` (páginas públicas, filtros, SEO, estados) e
`integracoes.md` (busca, feed, cache, auditoria).

### 4. Procedimento

#### P0 — Preparação (antes de qualquer agente)

1. Congelar o corpus: `git -C sucesu_analise rev-parse HEAD` (ou hash do tar) e
   `sha256sum` de `_indices/*.csv`.
2. Criar a cópia isolada e remover dela qualquer caminho para `sucesu-cms/` (atalhos,
   symlinks, `.git` que aponte para o repo).
3. Verificar que o corpus passa nos gates internos:
   `coverage.py --strict`, `lint_docs.py --strict-citations`,
   `merge_indices.py --check`. Se o corpus não passa, o exercício mede o corpus quebrado.
4. Sortear a ordem dos exercícios e registrar; não reutilizar o mesmo agente em duas
   unidades.
5. Preparar o “gabarito” separadamente (ver P3) e mantê-lo fora do alcance do agente.

#### P1 — Execução cega

1. Entregar apenas: o corpus, o diretório de saída e a lista de artefatos.
2. O agente lê os documentos da unidade, os índices e as dependências citadas.
3. O agente produz os artefatos e marca cada item como `[C]`, `[I]` ou `[L]`.
4. O agente não pergunta nada a humanos; dúvidas vão para `duvidas.md`.
5. Encerrar quando os artefatos estiverem completos ou quando o agente declarar bloqueio
   por lacuna — bloqueio é resultado válido, não falha do exercício.

#### P2 — Congelamento

1. Calcular hash de cada artefato.
2. Guardar o transcript da sessão (para auditar decisões, não para julgar estilo).
3. Não permitir edição posterior; correções vão para uma segunda rodada.

#### P3 — Construção do gabarito

O gabarito é extraído do **código real**, não dos documentos que estão sendo testados:

| Camada | Como extrair | Fonte |
|---|---|---|
| Schema | migrations + `_indices/tabelas.csv` conferido contra o DDL | `_indices/tabelas.csv`; migrations da unidade |
| Rotas | `_indices/rotas.csv` + arquivos `Routes/*.php` | `_indices/rotas.csv` |
| Telas | blades + `_indices/componentes.csv` | `_indices/componentes.csv` |
| Comportamento | controllers/services/models citados no doc | docs da unidade + código |
| PCs | checklist do doc da unidade | linhas listadas em `paridade.md` §3 |

O gabarito deve registrar, para cada item, a citação `caminho:linha` que o comprova.

#### P4 — Comparação

Comparar por chave, não por texto:

| Camada | Chave de comparação | Normalização |
|---|---|---|
| Schema | `tabela + coluna` | tipo canônico (`varchar(255)`, `uuid`, `jsonb`), nullability, default |
| Rotas | `método + URI` | ordem de middleware irrelevante; nome e ação comparados à parte |
| Telas | `rota + DOM id` | classes CSS e textos livres não contam; props/eventos contam |
| Comportamento | `PC ID` | passa / falha / não determinável |
| Integração | efeito observável | “remove do índice”, “invalida cache”, “grava auditoria” |

#### P5 — Classificação da divergência

| Classe | Definição | Ação |
|---|---|---|
| **DV-A — lacuna do corpus** | o dado não está em nenhum documento/índice; o agente só poderia adivinhar | corrigir o doc da unidade; abrir `LG-*` se não for recuperável |
| **DV-B — ambiguidade** | o dado está no corpus, mas duas leituras são possíveis | reescrever o trecho com exemplo/anti-exemplo |
| **DV-C — erro do agente** | o dado está claro e o agente ignorou | não alterar o corpus; registrar para calibrar o prompt |
| **DV-D — doc × código** | o doc afirma algo que o código não faz | decisão explícita: corrigir doc ou registrar bug; nunca copiar o bug |
| **DV-E — índice inconsistente** | CSV diverge do doc/código | corrigir índice e reexecutar `merge_indices.py --check` |

Severidade:

- **S1** — muda schema, rota, status code ou efeito de segurança.
- **S2** — muda tela, validação, mensagem ou integração.
- **S3** — cosmético, nome de classe, ordem de campos.

#### P6 — Ciclo de correção

1. Cada DV-A/DV-B/DV-E vira alteração no documento ou índice indicado.
2. DV-D vira decisão registrada em `riscos.md` (reproduzir ou corrigir).
3. Reexecutar **apenas** as camadas afetadas com um novo agente cego (não o mesmo).
4. Repetir até os limiares de §5.
5. Registrar a rodada, a data e o hash do corpus em `Evidências`.

### 5. Critérios de sucesso

| Métrica | C1 MailAudit | C2 FeedRss | C3 Agenda |
|---|---|---|---|
| Schema: tabelas/colunas corretas | ≥ 95% | ≥ 90% | ≥ 85% |
| Rotas: método+URI+middleware corretos | 100% | 100% | ≥ 90% |
| Telas: DOM ids/eventos corretos | ≥ 80% | ≥ 80% | ≥ 75% |
| PCs: passa | ≥ 90% | ≥ 80% | ≥ 75% |
| PCs: “não determinável” | ≤ 1 | ≤ 2 | ≤ 5 |
| Divergências S1 abertas | 0 | 0 | 0 |
| Divergências S2 abertas | ≤ 2 | ≤ 3 | ≤ 6 |

Um exercício só passa se **todas** as colunas da sua unidade forem atendidas. Um S1
aberto reprova o exercício independentemente da média.

### 6. O que cada exercício deve revelar

#### C1 — MailAudit

Perguntas que o corpus precisa responder sem o código:

- Quais são as 2 rotas, com middleware e permissão? (`_indices/rotas.csv`)
- O módulo escreve algo? (não: só `SELECT` em `v2_mail_logs`)
- Quais filtros existem e onde são aplicados? (em memória, sobre 200 registros)
- Por que o detalhe de um ID antigo responde 404? (o controller usa `getHistory(1)` e
  depois `firstWhere('id')`; só o mais recente abre)
- Quais dados sensíveis a tela mostra? (corpo integral do e-mail)
- Quais são as mensagens exatas de 403/404?

Se o agente reconstruir “detalhe por ID” de forma convencional, o corpus falhou em
documentar a particularidade central.

#### C2 — FeedRss (módulo)

Perguntas:

- O módulo gera o feed? (não; quem gera é `SVC-FEEDRSS` em `/feed.xml`)
- Quem pode acessar? (e-mail de suporte ou Sentinel `super-admin`; não é `v2_can`)
- Quais são as 3 rotas e o que cada uma escreve? (`enabled`, `deleted_at`, auditoria)
- Qual é o efeito no feed e por que pode demorar? (cache de página de 5 min)
- O que acontece ao remover e tentar republicar? (unique violation — decisão de
  reimplementação)

Se o agente criar tabela própria ou endpoint de criação, o corpus falhou em separar UI de
serviço.

#### C3 — Agenda

Perguntas:

- Quais são as 8 rotas (6 CMS + 2 públicas) e seus middlewares?
- Quais colunas e tipos de `v2_eventos`? (`event_date_start`, `event_date_end`,
  `topics_list`, `schedule`, `is_active`, `published_at`)
- Quais são os dois critérios de publicação e como diferem entre listagem, detalhe,
  sitemap, busca e RSS?
- Quais filtros de portal (`filter`, `search`, `date`, `week`, `month`) e qual o
  comportamento de cada um?
- Quais efeitos colaterais ao salvar/arquivar? (busca, feed, auditoria, cache)
- Quais telas CMS e portal, com quais DOM ids/eventos?

Se o agente tratar `published_at` e `is_active` como um único critério, o corpus falhou
na particularidade central.

### 7. Comparação com o código: o que é “igual”

Não se exige identidade textual. Exige-se equivalência observável:

| Item | Igual significa |
|---|---|
| Coluna | mesmo nome, tipo compatível e mesma nullability/default |
| Rota | mesmo método+URI; mesmo efeito de middleware (auth, CSRF, cache) |
| Status | mesmo código e mesma mensagem literal quando documentada |
| Tela | mesmos campos, DOM ids e eventos; layout pode variar |
| Efeito | mesma linha/arquivo/índice/cache/log afetado |
| Erro | mesma classe de erro e mesmo `code` de domínio |

## Particularidades

1. **Cego não é “sem documento”.** O agente lê o corpus inteiro, inclusive o doc da
   unidade. O que se testa é a **suficiência** do corpus, não a adivinhação.
2. **O gabarito não pode sair do mesmo doc.** Se o gabarito for copiado do `spec.md`, o
   exercício mede consistência interna, não fidelidade ao código. O gabarito vem das
   migrations, rotas e blades reais.
3. **Bloqueio é resultado.** Se o corpus não permite responder, o agente deve parar e
   registrar; forçar uma resposta plausível contamina a métrica.
4. **C1 e C2 são pequenos de propósito.** Eles calibram o protocolo e o formulário de
   comparação antes do C3, que tem 42 PCs e duas superfícies (CMS e portal).
5. **O mesmo agente não repete a unidade.** A segunda rodada usa outro agente, senão ele
   memoriza as correções e a métrica deixa de medir o corpus.
6. **O corpus tem defeitos conhecidos.** PCs como `PC-SLE-08`, `PC-SLE-12`,
   `PC-LSE-16`, `PC-BASICPAGE-13` e `R-GALLERY-05` foram corrigidos; o gabarito deve usar
   a versão corrigida (`paridade.md` §4). Se o agente cego reproduzir a versão antiga, é
   DV-D, não DV-C.
7. **Segurança entra na nota.** Reconstruir Gallery anônima ou `eval` de bloco é
   divergência S1 mesmo que o doc antigo descreva o comportamento.
8. **A métrica é por camada.** Um agente pode acertar 100% das rotas e 40% do schema; a
   média esconde isso. O relatório mostra as cinco camadas separadamente.

## Integrabilidade

### Receitas de uso

**1. Preparar uma rodada.**

```bash
# hash do corpus e dos índices
git -C sucesu_analise rev-parse HEAD
sha256sum sucesu_analise/_indices/*.csv > rodsada-01.indices.sha256
# copia isolada sem o repositorio legado
rsync -a --exclude '.git' sucesu_analise/ /tmp/cego-01/sucesu_analise/
test ! -e /tmp/cego-01/sucesu-cms && echo isolado
```

**2. Formulário mínimo de divergência.**

```text
DV-<exercicio>-NN | classe (A..E) | severidade (S1..S3) | camada
item esperado (citação do gabarito) | item produzido (citação do artefato)
decisão: corrigir doc / índice / prompt / nenhum
```

**3. Fechar uma rodada.**

```text
1. congelar artefatos + hashes;
2. comparar por chave (schema/rotas/DOM/PCs);
3. classificar e priorizar S1;
4. corrigir o corpus (nunca o gabarito para “combinar”);
5. repetir com agente novo;
6. anexar o relatório ao gate G5.
```

**4. Ler o resultado.**

Um S1 em schema/rota/segurança significa que o corpus ainda não é reimplementável
naquela unidade. Um S3 em texto de tela não bloqueia o gate, mas entra na lista de
correções da unidade.

## Anti-uso

1. **Dar ao agente o código ou o histórico da sessão.** Deixa de ser cego e mede memória,
   não corpus.
2. **Usar o `spec.md` como gabarito.** Mede auto-consistência; o gate exige comparação
   com o código.
3. **Aceitar “quase igual”.** Rota com middleware faltando, coluna com tipo diferente ou
   detalhe que abre qualquer ID são S1, não S3.
4. **Corrigir o corpus durante a rodada.** O agente precisa de um alvo estável; correções
   entram depois do congelamento.
5. **Reutilizar o agente.** Ele aprende as correções e infla a nota da segunda rodada.
6. **Executar os três em paralelo sem calibrar.** C1 e C2 calibram o formulário; C3 usa o
   formulário já estável.
7. **Tratar bloqueio como falha do agente.** Bloqueio por lacuna é o resultado que o
   exercício procura.

## Lacunas

| ID | Lacuna | Impacto |
|---|---|---|
| `LG-REIMPL-21` | Os três exercícios ainda não foram executados | o gate G5 permanece aberto (`PLANO.md:321`) |
| `LG-REIMPL-22` | Não há script de comparação automatizada de schema/rotas/DOM | a primeira rodada será manual e mais lenta |
| `LG-REIMPL-23` | Não há ambiente isolado padronizado para o agente cego | o isolamento precisa ser verificado a cada rodada |
| `LG-REIMPL-24` | Os documentos de Homepage/SobreNos/Seeds ainda não fecharam | não podem ser escolhidos para uma quarta rodada antes da Onda 5 |

## Evidências

- Gate G5: `PLANO.md:321`.
- Unidades e tamanhos: `00_inventario/manifest.json`;
  `05_modulos/Infraestrutura/MailAudit/spec.md:639-649`;
  `05_modulos/Infraestrutura/FeedRss/spec.md:677-687`;
  `05_modulos/Publicacoes/Agenda/spec.md:700-719`.
- Rotas: `_indices/rotas.csv` (Agenda: 6 CMS + 2 públicas; MailAudit: 2; FeedRss: 3).
- Contratos observáveis: docs das três unidades, §§1–3.
- Correções de PCs: `_qa/review-g2.md:76-153`; `_qa/review-g3.md:49-189`;
  `paridade.md` §4.
- Segurança: `_qa/security-g1.md:20-46`.