Acertar o status das specs e fixes nos quatro lugares onde ele vive¶

Motivação¶

O status de um documento existe em quatro lugares — o status: do front matter, a tabela de cabeçalho do próprio arquivo, a linha do índice e a entrada em metadata/catalog.yaml — e nada compara os quatro entre si. O scripts/docs_lint.py confere que o catálogo e os arquivos existem e combinam, mas não que digam a mesma coisa. O resultado é que seis specs estavam com valores diferentes em lugares diferentes, e a 0054 chegou a ter três: em-implementacao no front matter, CONCLUÍDA no corpo e aprovada no índice, já mesclada à main.

Isso importa porque o índice é o que alguém abre para saber o que está em pé. Uma spec no ar marcada como aberta se lê como trabalho pendente, e foi por isso que este ajuste começou como uma pergunta sobre o que tinha ficado em aberto.

Comportamento atual¶

SPEC-0049 e SPEC-0054 diziam em-implementacao estando mescladas — a 0049 com nota de versão 0.6.0 publicada.
SPEC-0048 e SPEC-0053 diziam concluida no arquivo e aprovada no índice.
SPEC-0035 e SPEC-0045 diziam em-implementacao de forma consistente nos quatro lugares, com um parágrafo do índice explicando que a migração de 2026-08-30 preservara o texto original de propósito.
FIX-0016 e FIX-0017 não apareciam na tabela do índice de fixes, que saltava de 0015 para 0018; a FIX-0017 também faltava no catalog.yaml — era o único apontamento do docs_lint.
O tweak de 2026-09-17 estava no catálogo mas fora da tabela de docs/tweaks/index.md.
Os textos de numeração dos dois índices ainda diziam "até SPEC-0047" e "até FIX-0015".

Comportamento desejado¶

As 53 specs e os 19 fixes dizem a mesma coisa nos quatro lugares, e as três tabelas de índice listam tudo o que existe em disco.

Escopo¶

Só documentação — docs/specifications/, docs/fixes/, docs/tweaks/ e docs/metadata/catalog.yaml. Nada em apps/.

Fora do escopo¶

As citações arquivo:linha das specs 0035 e 0054 não foram tocadas, e o make preflight acusa onze delas — uma na 0035, dez na 0054. Tocar o status: de um registro traz todas as citações daquele arquivo para o escopo da checagem, que é o que as expôs.

A da 0035 é defeito real e trivial: o texto cita routers/operations_center.py:23, caminho relativo, sem o prefixo apps/api/app/api/v1/. O arquivo existe; o caminho como está escrito não resolve.

As dez da 0054 são falso positivo de citacoes_dos_registros (scripts/preflight.py). Quando um parágrafo tem exatamente uma citação, a checagem toma o trecho entre crases mais longo do parágrafo e exige que ele esteja no arquivo citado. Nesses dez o trecho mais longo pertence a outra coisa: a identidade da RN27 (setup_paid + guarantee_paid + misc_paid + charge_paid == amount_paid), uma rota, um cabeçalho HTTP, um código de erro, e num caso um pedaço de prosa que o regex de trecho engoliu. A citação em si está certa — conferido em apps/api/app/models/billing.py:200, que é de fato o paid_at que o parágrafo descreve.

Duas coisas furam a proteção que o próprio verificador tem para isso (ele desliga o exame do trecho quando há mais de uma citação no parágrafo, por causa dos nove falsos positivos que uma tabela de endpoints já produziu): linha de tabela com uma citação só continua passando, e citação com intervalo de linhas é invisível ao regex — `scoping.py:42-48` não casa, então parágrafo com três citações é contado como tendo uma.

Corrigir as specs para agradar a checagem pioraria os documentos. O defeito é do verificador, e virou /fix próprio.

A primeira versão desta seção dizia outra coisa, e estava errada. Afirmava que as onze eram citações que envelheceram e que reapontá-las faria o registro mentir sobre o código do dia em que foi escrito. Foi escrita sem abrir uma única delas — o commit 3c43db6 carrega o mesmo erro na mensagem. Ao menos uma das citações acusadas está exata.

Alterações propostas¶

docs/specifications/index.md — quatro linhas de status, o texto de numeração, e o parágrafo sobre 0035/0045 trocado por uma nota dizendo onde o status vive e que o linter não compara os quatro.
docs/specifications/00{35,45,49,54}-*/specification.md — status:, updated: e a linha da tabela de cabeçalho.
docs/fixes/index.md — as duas linhas que faltavam e o texto de numeração.
docs/tweaks/index.md — o tweak de 2026-09-17 e este.
docs/metadata/catalog.yaml — FIX-0017 acrescentada; status de SPEC-0035, SPEC-0045, SPEC-0049 e SPEC-0054.

Impactos¶

Nenhum no produto — o apps/ não foi tocado, então não há comportamento novo para alguém de fora perceber.

Reverte uma decisão registrada, e é o aviso que o CLAUDE.md pede: o parágrafo do índice das specs declarava que o status defasado de SPEC-0035 e SPEC-0045 era preservação deliberada do texto da migração. A fidelidade fazia sentido na migração e deixou de fazer depois; o parágrafo novo registra a correção e cita a evidência de merge no Git — commit 6753bab para a 0035, merge 6d3e165 para a 0045.

Validação¶

python3 scripts/docs_lint.py — verde, 95 documentos, catálogo consistente (antes apontava a FIX-0017 ausente). Um cruzamento dos quatro status de cada spec e fix não devolve divergência nenhuma; as 53 specs estão em concluida.

make preflight falha na checagem de citação, por defeito do próprio verificador que este ajuste não criou, só expôs — ver Fora do escopo.

Documentos relacionados¶

ADR-0004 — documentação como código, que é o que faz do status um dado versionado em vez de uma anotação.