Schema de metadados¶

Todo documento "de primeira classe" (specification, fix, tweak, decision, architecture, operation, api) carrega front matter YAML no topo do arquivo. Este arquivo documenta o schema e a lista fechada de valores aceitos — é o que scripts/docs_lint.py valida.

Campos¶

---
id: SPEC-0001              # obrigatório — ver "IDs" abaixo
type: specification        # obrigatório — ver "Tipos controlados"
title: "Título do documento"
status: concluida           # obrigatório — ver "Status por tipo"
version: 1.0                # só em specification; opcional nos demais
severity: média              # só em fix, quando registrado na origem
domains: [analise-de-credito]      # inferido do conteúdo — nunca vazio (usa "geral" quando não dá pra classificar)
components: [api, web]             # apps/áreas afetadas — omitido quando o documento não afeta código
related:
  specs: [SPEC-0034]
  fixes: []
  tweaks: []
  decisions: []
  tests: []
created: 2026-08-11          # data de criação, quando determinável pela fonte original
updated: 2026-08-30          # data do último commit que tocou o arquivo
---

Regra geral: nenhum campo é inventado. Quando a informação não existe na fonte original (ex.: um fix.md antigo sem "Fechado em"), o campo é omitido — não recebe null nem um valor de preenchimento. owners é um caso à parte: nenhum documento migrado tem responsável nomeado na origem, então o campo simplesmente não aparece em nenhum deles; ele existe no schema para specs futuras que já nasçam com essa informação.

Tipos controlados¶

specification · fix · tweak · decision · architecture · operation · api

Status por tipo¶

Os valores preservam a máquina de estados que cada tipo já tinha em português antes da migração — não foram traduzidos nem reduzidos a um draft/approved genérico, porque isso perderia distinções que o fluxo de specs e fixes segue checando (ex.: um RASCUNHO de spec não é a mesma coisa que um DIAGNOSTICADO de fix).

Tipo	Valores permitidos
`specification`	`rascunho` → `aprovada` → `em-implementacao` → `concluida`
`fix`	`rascunho` → `diagnosticado` → `em-correcao` → `corrigido`
`tweak`	`feito` (registro histórico; o ajuste direto não gera mais arquivo — a mensagem de commit é o registro)
`decision`	`proposta` · `aceita` · `substituida` · `rejeitada` (nomenclatura padrão de ADR)
`architecture`, `operation`, `api`	`atual` · `desatualizado` (o segundo é um sinal para revisão, não um erro de build)

IDs¶

SPEC-NNNN e FIX-NNNN preservam o número que o documento tinha em spec/NNNN-slug/ e fix/NNNN-slug/ antes da migração (2026-08-30) — é o mesmo número da branch Git que o criou. Nunca são renumerados.
ADR-NNNN é sequencial dentro de decisions/, começando em 0001.
tweak não tem número e é só histórico (registros de 2026-08-30 a 2026-10-15, nome <data>-<slug>.md). O ajuste direto de hoje não gera arquivo — ver Fluxo de desenvolvimento no CLAUDE.md da raiz.

`domains` e `components`¶

domains é inferido por palavra-chave do título/slug de cada documento migrado (ex.: "credito", "pendencia" → analise-de-credito) — é uma classificação derivada do próprio conteúdo, não uma taxonomia inventada à parte. components reflete os apps citados na tabela de cabeçalho original (api, web, e2e, infra, skills), respeitando quando o próprio documento diz "sem impacto" para um deles.

Validação¶

python3 scripts/docs_lint.py roda a partir da raiz do repo e verifica:

todo arquivo com front matter tem YAML válido;
id é único no repositório inteiro (specs, fixes, ADRs juntos);
type e status pertencem às listas acima;
toda entrada de metadata/catalog.yaml aponta para um arquivo que existe;
todo arquivo com front matter tem uma entrada correspondente no catálogo;
links relativos [texto](caminho) dentro de docs/ resolvem para um arquivo existente.

Ver operations/documentation-platform.md para como isso se encaixa no make preflight.