diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da308f6..38b5efd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Guia de Contribuição e Método de Trabalho (UTF-SDD) +# Guia de Contribuição e Método de Trabalho (UTF-SDD) Bem-vindo ao repositório! Este documento explica como trabalhamos aqui. Leia antes de iniciar sua primeira entrega e volte a ele sempre que tiver dúvidas sobre "como eu deveria estar fazendo isso". @@ -18,7 +18,7 @@ Você é o Engenheiro e o Arquiteto; a IA é a sua equipe de execução. - **A branch `main` é sagrada:** Ela reflete a produção e possui bloqueio de commits diretos. - **Trabalho:** Crie uma branch curta **a partir da `main`** para cada Issue (feature branch). -- **Integração:** Ao finalizar, abra um Pull Request contra a `main` com `Closes #`. O CI (Jest + lint, contra um PostgreSQL em container) precisa passar antes do merge. +- **Integração:** Ao finalizar, abra um Pull Request contra a `main` com `Closes #`. O CI (testes + lint, contra um PostgreSQL em container) precisa passar antes do merge. --- @@ -32,6 +32,7 @@ Nada é duplicado neste projeto. Informação repetida diverge. | **Produto** | `docs/prd.md` | O que o sistema faz (Glossário, Atores, Histórias). | | **Arquitetura** | `docs/architecture.md` | Onde as coisas estão (estrutura, entidades, contratos). | | **Jornadas** | `docs/user-flows.md` | O caminho do usuário e onde ele desiste. | +| **Ficha** | `docs/checklist.md` | As regras da disciplina, os IDs e as entregas — a régua dos workflows. | | **Especificação** | `specs/-/` | O `spec.md` (o que fazer), o `plan.md` (tarefas técnicas) e `reviews/` (pareceres e triagem). | | **Leis da IA** | `.agents/` | `rules/utf-rules.md` (constituição, carregada via `CLAUDE.md`), `workflows/` (ciclos) e `agents/` (prompts dos subagentes). | @@ -39,16 +40,18 @@ Nada é duplicado neste projeto. Informação repetida diverge. ## 🔄 O Ciclo de Trabalho -Todo trabalho que altera o comportamento do sistema segue o ciclo SDD, orquestrado pelos agentes do repositório: `/utf-issue ` inicia (spec → plano), `/utf-task ` executa cada tarefa com tutor, implementador de contexto limpo e dois revisores distintos, e o auditor final confere o diff inteiro antes do PR. +Todo trabalho que altera o comportamento do sistema segue o ciclo UTF-SDD, orquestrado pelos agentes do repositório: `/utf-issue ` inicia (spec → plano), `/utf-task ` executa cada tarefa com tutor, implementador de contexto limpo e dois revisores distintos, e o auditor final confere o diff inteiro antes do PR. - **O passo a passo operacional** (comandos e o que fazer em cada pausa) está no [Tutorial do Método](./docs/tutorial-sdd.md). - **O porquê de cada regra** está no [Guia da Disciplina](./docs/guia-sdd.md). -O que é **norma inegociável** deste repositório são os três portões humanos — nenhum agente passa por eles em seu lugar: +O que é **norma inegociável** deste repositório são os cinco portões humanos — nenhum agente passa por eles em seu lugar: 1. **🚪 Spec:** só você aprova, trocando `status: rascunho` → `status: aprovada` num commit seu. -2. **🚪 Triagem:** só você aceita ou recusa apontamentos de revisão (recusa exige justificativa, registrada em `specs/-/reviews/tarefa-NN-decisoes-rN.md`). -3. **🚪 Pull Request:** só você escreve a explicação, com as suas palavras, listando os apontamentos aceitos e recusados. +2. **🚪 Explicação do tutor:** cada tarefa só é implementada depois do seu "pode implementar" — dúvida agora custa cinco minutos; depois do diff, custa uma rodada. +3. **🚪 Triagem:** só você aceita ou recusa apontamentos de revisão (recusa exige justificativa, registrada em `specs/-/reviews/tarefa-NN-decisoes-rN.md`). +4. **🚪 Commit:** revisores aprovarem não basta — o orquestrador apresenta o diff e os pareceres e só commita com o seu "pode commitar". +5. **🚪 Pull Request:** só você escreve a explicação, com as suas palavras, listando os apontamentos aceitos e recusados. --- diff --git a/docs/guia-sdd.md b/docs/guia-sdd.md index 1be92e4..aa05536 100644 --- a/docs/guia-sdd.md +++ b/docs/guia-sdd.md @@ -57,15 +57,16 @@ por isso que existe o `docs/architecture.md`: para escrever, uma vez, quais são ## 2. Os artefatos -Todo trabalho gira em torno de onze artefatos. Eles são a matéria-prima da sua nota. +Todo trabalho gira em torno de doze artefatos. Eles são a matéria-prima da sua nota. | Artefato | Onde fica | Para que serve | | --- | --- | --- | | **`README.md`** | raiz | A vitrine: o que é, quem fez, como rodar, link em produção. | | **`prd.md`** | `docs/` | O que o produto faz: glossário, atores, histórias. | | **`architecture.md`** | `docs/` | Onde as coisas estão: estrutura, entidades, estados, contratos. | +| **`checklist.md`** | `docs/` | A ficha da disciplina: regras do projeto, IDs e entregas — a régua dos workflows. | | **`user-flows.md`** | `docs/` | O que a pessoa vive na tela, e onde ela desiste. | -| **Tokens de design** | `docs/` ou `apps/web/` | Cores, espaçamento, tipografia — para a IA não inventar um botão por tela. | +| **`design-tokens.md`** | `docs/` | Cores, espaçamento, tipografia — para a IA não inventar um botão por tela. | | **Issue** | GitHub Projects | A unidade de trabalho. Uma história de usuário. | | **`spec.md`** | `specs/-/` | O que precisa existir e como saber que ficou pronto. | | **`plan.md`** | `specs/-/` | Como será construído, em tarefas pequenas. | @@ -73,10 +74,10 @@ Todo trabalho gira em torno de onze artefatos. Eles são a matéria-prima da sua | **Código** | `apps/api`, `apps/web` | O que a IA escreve seguindo o plano. | | **Pull Request** | GitHub | Onde você explica, com suas palavras, o que foi feito. | -Desses onze itens, a IA produz sozinha apenas **o código, o plano e os pareceres**. -Todo o resto precisa da sua direção. +Desses doze itens, a IA produz sozinha apenas **o código, o plano e os pareceres**. +A ficha vem pronta com o template; todo o resto precisa da sua direção. -E existe um décimo-segundo, que é um índice e não um artefato: o `specs/README.md`, +E existe um décimo-terceiro, que é um índice e não um artefato: o `specs/README.md`, descrito no fim do §4. --- @@ -346,6 +347,7 @@ confiar. | `docs/architecture.md` | **onde as coisas estão** — estrutura, entidades, contratos, estados | | `docs/user-flows.md` | **o que a pessoa vive** — jornadas e pontos de desistência | | `docs/design-tokens.md` | **como o produto se parece** — paleta, espaçamento, tipografia | +| `docs/checklist.md` | **o que a disciplina exige** — regras, IDs e entregas | | `specs/` | **o que está sendo construído agora** — uma pasta por história | Se você precisa saber o status do pedido, existe **um** lugar: a máquina de estados no @@ -489,7 +491,7 @@ status: rascunho # rascunho | aprovada > o pedido permanece AGUARDANDO e reaparece no painel dele com o botão de retomar"* — > isso é testável. *"Tratar o abandono"* não é. -### Passo 3 — 🚪 Primeiro portão humano: você aprova a spec +### Passo 3 — 🚪 Portão: você aprova a spec **Você lê a especificação inteira e decide se ela está certa.** Não é carimbo. É aqui que você define o que conta como "certo" — e tudo depois disso obedece a essa definição. @@ -638,8 +640,10 @@ Duas coisas, nessa ordem: 1. **Chame o tutor** (§6) e entenda o que foi feito. É agora, com a tarefa fresca e pequena, que entender custa barato. -2. **Pare.** O orquestrador marca a tarefa como feita no `plan.md`, faz o commit, e - devolve o controle. Você pede a próxima quando quiser. +2. **Pare — 🚪 o commit é um portão.** O orquestrador apresenta o resumo do diff e os + dois pareceres, e espera o seu **"pode commitar"**. Só então ele marca a tarefa + como feita no `plan.md`, faz o commit e devolve o controle. Revisor aprovar não + substitui o olho do dono. Você pede a próxima quando quiser. > **Você trabalha na sua branch, na sua IDE, com os arquivos à vista.** Esta disciplina > **não** usa worktrees nem ambientes isolados. Worktree serve para deixar vários @@ -668,7 +672,7 @@ O auditor também confere quatro coisas que ninguém mais confere: uma Issue aberta correspondente? - **Escopo do PR:** entrou no diff algo que a spec não pedia? -### Passo 7 — 🚪 Segundo portão humano: você abre o PR +### Passo 7 — 🚪 Portão final: você abre o PR Você lê o diff, escreve a explicação com suas palavras e abre o Pull Request com `Closes #27`. diff --git a/docs/tutorial-sdd.md b/docs/tutorial-sdd.md index 0cd7536..f5179b6 100644 --- a/docs/tutorial-sdd.md +++ b/docs/tutorial-sdd.md @@ -6,8 +6,9 @@ Git e de PR estão no [CONTRIBUTING](../CONTRIBUTING.md). > A regra que resume tudo (é o que dá nome ao método — **UTF-SDD, um SDD por > Portões**): **a IA escreve o código; você decide nos portões.** -> São três portões por história — aprovar a spec, aceitar a explicação do tutor -> antes de cada tarefa e fazer a triagem dos apontamentos — mais o PR no fim. +> São quatro portões por história — aprovar a spec, aceitar a explicação do +> tutor antes de cada tarefa, fazer a triagem dos apontamentos e **autorizar +> cada commit** — mais o PR no fim. --- @@ -77,7 +78,7 @@ Dentro do comando acontece o ciclo completo, com as suas paradas: | Revisão em paralelo | revisor-conformidade + revisor-codigo | nada — quem despacha é o fluxo | | Pareceres gravados em `reviews/` | orquestrador | nada | | **Triagem** (se houve apontamentos) | orquestrador apresenta a lista | **🚪 aceita ou recusa cada um** — recusa exige justificativa, registrada em `reviews/tarefa-NN-decisoes-rN.md` | -| Commit `tarefa 1: ...` | orquestrador | confere o diff na IDE; `/utf-tutor 1` se quiser a aula | +| Commit `tarefa 1: ...` | orquestrador apresenta o diff e os pareceres | **🚪 confere o diff na IDE e autoriza** ("pode commitar"); `/utf-tutor 1` se quiser a aula | Repita para cada tarefa: `/utf-task 2`, `/utf-task 3`… — ou apenas `/utf-task`, que pega a próxima pendente do `plan.md` e avisa quando não