Lacuna sob demanda¶

O fluxo para quando um pedido chega — por Slack ou pelo chat — e o item pedido (uma fonte ou uma função) não existe no wiki. Em vez de responder de cabeça, o wiki cresce: pesquisa citada, página e template.

Em uma frase

Pedido que não está no wiki → vira uma ficha de lacuna (página) e um template de código — com as fontes citadas. O mesmo fluxo serve para as funções utilizadas pelo fonte.

O fluxo¶

Checar antes de responder. O item já existe?
buscar_wiki / ler_pagina no MCP, ou grep em docs/ e examples/.
Se existe: responde-se com o link. O fluxo termina aqui.
Se não existe: abre-se a lacuna.
Abrir a lacuna — a checagem de duplicidade e o andaime são automáticos:
```
python3 scripts/lacunas/abrir.py "Ler SD1 por filial" --tipo fonte \
    --tabelas SD1 --funcoes "xFilial,GetArea,RestArea" \
    --canal slack --pedido-por joao --pedido "preciso ler os itens da NF"
```
O comando recusa se o item já existir (em lacunas/, examples/ ou docs/) e diz onde está — é essa recusa que caracteriza a lacuna. Cria:

Arquivo O que é

lacunas/<slug>.md a ficha — pedido, pesquisa, recursos, fontes (fonte da verdade)

examples/<slug>.md o template de código, no estado nao-avaliada
Pesquisar com citação. Cada afirmação carrega [n] e a URL entra em docs/pesquisa/ledger.json. Onde não há fonte, escreve-se > **Lacuna:** não encontrado — <o que falta buscar> — nunca prosa plausível.
As funções utilizadas recebem o mesmo tratamento. Cada função que o fonte usa e que ainda não tem ficha ganha a mesma ficha, com o mesmo comando e --tipo funcao:
```
python3 scripts/lacunas/abrir.py "xFilial" --tipo funcao --canal slack
```
O gerador liga as duas pontas sozinho: a página do fonte lista, em Recursos utilizados, cada função com link para a ficha dela quando existir. 5. Publicar. mkdocs build, commit e push para main — o push reconstrói o site e o MCP (não há etapa de revisão entre o push e a produção).

O que o gerador produz¶

A fonte da verdade é lacunas/. scripts/lacunas/gerar_lacunas.py — rodado no build da imagem, como o gerador de exemplos — deriva:

docs/lacunas/index.md — o registro de lacunas, com estado;
docs/lacunas/<slug>.md — a ficha renderizada, com a tabela de Recursos utilizados e a lista de Fontes resolvida a partir do ledger.

Não edite docs/lacunas/ à mão: é artefato de build.

Estados¶

Estado	Significa
🔴 `aberta`	Pedido registrado; pesquisa não feita. O conteúdo é esqueleto.
🟡 `pesquisada`	Pesquisa citada; o código ainda não foi validado num Protheus real.
🟢 `publicada`	Pesquisa citada e revisada.

O template¶

O template de código nasce de templates/ (fonte.advpl ou funcao.advpl) com ProtheusDOC e um // TODO, no estado nao-avaliada — código gerado não é código testado, e a página carrega esse aviso até alguém rodar e registrar como testou. Sem RDMake/TDS, "compilou" é uma afirmação que ninguém aqui pode fazer.

Regras que o fluxo protege¶

Não inventar. Sem fonte, é lacuna declarada.
Não duplicar. O abrir.py recusa item que já existe e aponta o caminho.
Uma função é uma lacuna como outra qualquer. O mesmo formato e o mesmo comando — é por isso que a ficha tem tipo: fonte | funcao.
O estado fica à vista. Nada entra como conhecimento estabelecido sem teste.

Arquivo	O que é
`lacunas/<slug>.md`	a ficha — pedido, pesquisa, recursos, fontes (fonte da verdade)
`examples/<slug>.md`	o template de código, no estado `nao-avaliada`