Como ler

O Twelves Specs é o lugar onde as regras do Twelves estão escritas para quem decide. Cada página descreve uma regra em vigor: o que acontece, com que números, porquê, onde vive no código e o que a protege. O projeto continua a ser o mesmo — o caçador de preço, a carteira fictícia, o painel —; o que muda é que a regra deixa de estar espalhada por ficheiros escritos para o Claude e passa a ter uma página que se lê em dois minutos.

O que esta página não é

Não é documentação de código, nem o diário de decisões, nem um sítio onde se escrevem regras novas. As regras decidem-se no projeto; aqui só se descrevem as que já estão a correr. Uma página nunca inventa uma regra que o código não tem, nem a «arredonda» para ficar mais bonita.

Os três estados

• Em construção — a página foi rascunhada a partir das fontes, mas o Claude ainda não leu a função citada contra o texto. Pode ter erros. O selo aparece na barra lateral e na ficha da página.
• Vigente — o Claude verificou cada afirmação contra o código e carimbou a data e o commit em que o fez. É isto que se pode citar.
• Retirada — a regra deixou de existir; a página fica, com a data, para a história ligar.

A anatomia de uma página

1. A ficha, logo abaixo do título: o estado, a data e o commit da verificação, o capítulo, os ficheiros e funções onde a regra vive, as flags e limiares, os testes que a protegem e as datas das decisões. Nada disto é escrito à mão: vem do cabeçalho da página e um teste confere, a cada commit, que cada ficheiro, função, teste e data existem mesmo.
2. A regra — o vigente, em poucas linhas, sem siglas, com os números do código.
3. Requisitos de negócio — uma tabela: o que o sistema garante ou proíbe, a decisão com data que o criou, onde vive no código e o que o protege (um id R-01, R-02… por página, estável).
4. Diagramas — o fluxo, a sequência do dia ou os estados, desenhados a partir do texto da própria página (o diagrama é texto na página e um teste recusa-o quando não desenha).
5. Porquê — a decisão e a data.
6. Onde está no código — a função e o módulo, por ordem de leitura.
7. O que a protege — a flag, o teste, o portão.
8. O que NÃO faz — as fronteiras: o que a regra não decide e o que fica para o David.
9. Ligações — outras páginas e as hipóteses do laboratório.

Como se mantém igual ao código

As páginas vivem ao lado do código, no repositório do projeto, e a mesma alteração que muda uma regra muda a página. Três mecanismos garantem que isso acontece, sem depender da memória de ninguém:

• A regra de trabalho: mudar uma regra = mudar o texto em vigor, registar a decisão com data no diário e atualizar a página da spec.
• O portão dos commits: uma alteração de código tem de dizer, na própria mensagem, que páginas mudaram com ela (Spec: …) ou porque nenhuma mudou (Spec: sem mudança — razão). Durante a escrita dos capítulos o portão avisa; a partir de 15 de novembro nega.
• O teste de deriva: cada flag e cada módulo do projeto têm de ter uma página dona; cada fonte citada tem de existir; uma página só é «vigente» com um commit de verificação real. Enquanto houver capítulos por escrever, o índice di-lo.

Este site só renderiza: copia as páginas do projeto e desenha-as com a identidade do painel — os mesmos tokens de cor, as mesmas letras, o mesmo logótipo. Nada aqui foi desenhado de novo.

Onde começar

O índice das specs lista os capítulos e o estado de cada um. Os capítulos escrevem-se entre 9 e 14 de novembro de 2026; até lá, a maior parte aparece como «em construção».