docs: auditoria de coerência — branch antes da spec, portão exigido no merge, entregas do Moodle

[ronifabio]

O que este PR faz e por quê

Auditoria de leitura completa do template (README, CONTRIBUTING, guia, tutorial, checklist, os oito workflows, os cinco agentes e as cascas das quatro ferramentas) atrás de contradições entre os documentos. O método pede que nada seja duplicado, mas README, CONTRIBUTING, tutorial e guia repetiam as mesmas regras com versões diferentes, e o CONTRIBUTING tinha ficado para trás.

Cinco contradições mudavam o que o aluno faz e foram corrigidas:

1. Portão de Entendimento. O CONTRIBUTING dizia 200 caracteres, só em PR que altera apps/, reprovação se não tocar docs/, e liberava PR de manutenção "direto". O template de PR, o YAML e o guia §9 dizem 400, em todo PR. CONTRIBUTING alinhado ao mecanismo real.
2. O Portão não bloqueava merge. A proteção da main aplicada pelo setup usava required_status_checks: null, então o check ficava vermelho e o merge seguia. O setup passa a exigir o job explicacao, e o guia deixa de prometer o que a proteção não fazia.
3. Quando a branch nasce. O usuário commitava status: aprovada no Passo 1, mas a branch só era criada no Passo 3 — o commit caía na main bloqueada. A branch agora nasce no início do /utf-issue; rascunho da spec, aprovação e plano são os três primeiros commits, antes de qualquer código. Workflow, guia (Passos 2 a 4, §10, diagrama §5) e tutorial atualizados.
4. Bug exige spec ou não. Constituição §3 e guia §4 dizem que não; o FAQ do guia dizia que sim. FAQ alinhado à constituição, com a regra de quando um "bug" é na verdade história nova.
5. Versões no architecture.md. O guia listava como anti-padrão; o esqueleto e o workflow pediam. Regra única: a linha principal (major) fica no documento, porque o setup escolhe o gerador por ela; o pin exato vive no package.json.

Desalinhamentos menores também corrigidos: esqueleto da spec (as sete seções) passa a constar no workflow da Issue, já que auditor e revisor cobram essas seções; referências a "Passo 3/5/6" com numeração do guia dentro de workflows e agentes viraram nome; glossário do PRD no guia trazia entidade em inglês (duplicava o glossário técnico); coluna Blocked no Kanban, que o guia já mandava usar; mapa de domínios sem tabela de rotas à mão; .github/ vem do template e não do setup; contagem de portões (quatro por história e um quinto no PR) igual nos quatro documentos; "quatro comandos" em tabela de cinco; OpenCode fecha por allowlist, não por prompt; nota no README e no tutorial de que no Antigravity o comando é o nome do arquivo em .agents/workflows/.

O segundo commit alinha a ficha e o guia às entregas do Moodle: E1 é "Planejamento e Setup" (Fase 0 + PR do setup, sem spec), E3 é "Frontend, Pagamento e Deploy", atividades semanais valem 10 pontos e entrega sem vídeo não pontua. Sem datas — a ficha vale para qualquer semestre.

CONTRIBUTING.md estava com CRLF e foi normalizado para LF conforme o .gitattributes, por isso o diff dele parece maior do que é (git diff -w mostra as 14 linhas reais).

Apontamentos da revisão

Não se aplica.

🤖 Generated with Claude Code

[ronifabio]

Terceiro commit: segunda auditoria, feita por um agente de leitura independente e confirmada ponto a ponto. Seis brechas que os dois primeiros commits não cobriam, quatro delas no ciclo por tarefa:

1. Diff vazio para os revisores. git diff <SHA>..HEAD compara dois commits; como o implementador não commita, HEAD == SHA e o parecer da rodada 1 saía APROVADO sobre nada. Agora o orquestrador faz git add -A (sem commit) e o diff é git diff <SHA> contra o working tree.
2. Tutor "depois" antes do commit. O ciclo oferecia /utf-tutor n antes do "pode commitar", mas o tutor localiza a tarefa pelo commit. A aula agora vem depois do commit; antes, o aluno confere o diff com o roteiro do tutor "antes".
3. Sem comando para fechar a Issue. Nada disparava auditor, docs e PR. /utf-issue n ganhou retomada: lê o estado da pasta specs/ e entra no passo certo. Ordem do fechamento: docs → commit → auditor → prova → PR.
4. Estouro das 2 rodadas sem saída. Pareceres ficavam untracked (o git clean os levava) e a contagem em disco impedia reexecutar a tarefa. Agora: commit dos pareceres antes da limpeza e arquivamento em reviews/arquivo/<data>/ ao recomeçar.
5. /utf-tutor antes 3 perdia o número no Claude Code ($1 → $ARGUMENTS).
6. O comentário do template de PR contava 252 caracteres para o Portão. O CI passa a descartar comentários HTML antes de contar (verificado: template intocado → 0).

Mais 20 ajustes menores, listados na mensagem do commit.

[ronifabio]

Sexto commit, fechando as lacunas que sobraram — precedido de um teste do ciclo num repositório de brinquedo.

O teste. Simulei a Issue #27 do começo ao fim num repositório descartável e verifiquei nove afirmações que os workflows fazem. Todas passam depois das correções:

Verificação	Resultado
Branch antes da spec: três commits (rascunho, aprovação, plano) antes de qualquer código	passa
/utf-task sem número resolve a primeira - [ ] do plano	passa
git add -A + git diff <SHA> mostra arquivo novo e alterado	passa (14 linhas)
O comando antigo git diff <SHA>..HEAD	0 linhas, como suspeitado
git diff <SHA> sem o add -A	perde o arquivo novo
Glob de rodada com NN de dois dígitos	passa, e não casa com um dígito
Grep ancorado ^tarefa 3:	acha 1 commit; o antigo achava 2, pegando tarefa 30
Pareceres commitados sobrevivem a git restore + git clean	passa
Arquivar em reviews/arquivo/ zera a contagem da tarefa	passa

O que entrou.

• specs/_modelo/spec.md e plan.md: os dois artefatos do ciclo não tinham esqueleto, só a Fase 0 tinha. São comentados, e o workflow da Issue passa a apontar para eles em vez de repetir as seções — a estrutura mora num lugar só. O modelo fica fora do índice e da auditoria.
• .github/ISSUE_TEMPLATE/ com bug e tarefa técnica, mais uma seção no tutorial com o passo a passo. No bug, o primeiro commit é o teste que reproduz a falha.
• Apêndice C do guia: esteira de CI de referência, com service container do Postgres e health check, para a Issue do ID18. O repositório continua sem gerar CI além do Portão.
• Quem assina o quê: o PR é sempre do aluno; no commit a decisão é dele e a execução varia. Estava implícito em dois padrões diferentes.