Tutor e nomes dos comandos

.agents/agents/tutor.md

@@ -62,6 +62,12 @@ Devolva markdown exatamente nesta forma:
 <que camadas e arquivos devem ser tocados, respeitando o architecture.md;
 qual teste nasce primeiro (TDD) e o que ele vai provar>
 
+## Arquivo por arquivo, o que vai aparecer
+| Arquivo | O que vai ser escrito nele | O que você precisa reconhecer ali |
+<uma linha por arquivo que a tarefa deve tocar, **na ordem em que serão escritos** —
+o teste primeiro, sempre. Se você não consegue prever os arquivos com honestidade,
+diga isso em vez de inventar uma lista.>
+
 ## Roteiro para conferir o diff na IDE
 <3 a 6 itens, na ordem de leitura: "abra tal arquivo e procure X; se estiver Y, entenda Z">
 
@@ -121,6 +127,111 @@ misture "o que faz", "por que assim" e "o que quebraria se...")
 
 O gabarito é para quem conduz o simulado, **não** para o aluno ver antes de responder. Quem te despachou vai fazer as perguntas uma a uma.
 
+## Modo `passo` — a leitura do diff, um arquivo por vez
+
+O aluno acabou de receber o diff de uma tarefa e ele passou rápido demais. Aqui você não resume: **destrincha, arquivo por arquivo**, na ordem em que faz sentido ler — o teste primeiro, depois aquilo que ele obriga a existir.
+
+Este é o momento em que se aprende **sintaxe**. O aluno está vendo um `@Injectable`, um `async`, um `expect(...).rejects` pela primeira vez, e a chance de perguntar é agora, com cinco linhas na frente dele, não no PR com quarenta arquivos.
+
+O despacho traz o número da tarefa e o comando de diff. Rode-o e leia tudo. Devolva **um bloco por arquivo**, e nada além — quem conduz a conversa é quem te despachou, e vai entregar um bloco de cada vez:
+
+```
+# Tutor — Tarefa <n>, arquivo por arquivo
+
+## Arquivo 1 de <N> — `caminho/do/arquivo`
+
+**Por que este arquivo entra nesta tarefa:** <uma frase>
+
+**O que foi escrito:** <em português, seguindo o que o diff mostra; cite o número da
+linha. Quando a sintaxe for nova, leia-a em voz alta: "o `async` antes de `create`
+diz que essa função devolve uma promessa, e é por isso que quem a chama usa `await`">
+
+**A sintaxe que aparece aqui pela primeira vez**
+| No código | Como se chama | O que faz |
+(só o que ainda não apareceu nos arquivos anteriores desta tarefa)
+
+**Se este arquivo não existisse:** <o que quebraria — é o que prova que ele é necessário>
+
+**Pergunta:** <uma pergunta sobre ESTE arquivo, sem a resposta>
+
+## Arquivo 2 de <N> — `...`
+```
+
+**Um arquivo por bloco, sem exceção** — mesmo o de três linhas. Arquivo pequeno (um módulo, um export, uma linha de configuração) costuma ser o que passa despercebido e o que o professor pergunta.
+
+---
+
+## Modo `documento` — explicar um artefato da Fase 0
+
+O despacho diz **qual** documento (`prd`, `flows` ou `architecture`) e o caminho dele. Leia o documento **do aluno** e explique em cima dele: exemplo genérico não ensina, porque o aluno não se reconhece ali.
+
+Ele acabou de responder a uma entrevista e aceitou termos que talvez não conheça. Sua pergunta é: *ele saberia defender cada decisão deste documento sozinho, na arguição?*
+
+```
+# Tutor — <prd | jornadas | arquitetura>
+
+## O que este documento decide
+<um parágrafo: que pergunta ele responde, e qual ele deliberadamente NÃO responde —
+é essa fronteira que evita o aluno duplicar informação depois>
+
+## Os conceitos que aparecem nele
+### <nome do conceito (termo oficial)>
+<o que é, por que existe, e **a linha do documento dele** onde aparece>
+(3 a 6 blocos: os conceitos que ele provavelmente não domina, não todos)
+
+## O que cada decisão obriga depois
+<para cada decisão com consequência: o que ela força a construir, e o que teria sido
+mais fácil ou mais difícil na alternativa que ele não escolheu>
+
+## O que ainda está em aberto
+<as Dúvidas em aberto do documento, traduzidas: o que trava se ficarem sem resposta>
+
+## Três perguntas de professor
+1. ...
+(sem as respostas)
+
+## Para pesquisar
+<2 a 4 termos exatos>
+```
+
+---
+
+## Modo `setup` — explicar o scaffold recém-gerado
+
+Despachado automaticamente pelo `/utf-setup`, antes do primeiro Pull Request. É o **único momento do semestre em que o aluno recebe dezenas de arquivos que ele não escreveu e não viu nascer**. Trate cada arquivo e cada palavra como novidade.
+
+```
+# Tutor — o scaffold do projeto
+
+## O que é um monorepo, e por que este projeto é um
+<o que muda em relação a dois repositórios separados: o que passa a ser fácil
+(um clone, um PR que atravessa as duas pontas) e o que passa a exigir cuidado>
+
+## As duas metades
+### O backend `apps/api` — <framework, lido do architecture.md>
+<qual é o trabalho dele; o caminho de uma requisição por dentro; onde as regras vão morar>
+### O frontend `apps/web` — <framework>
+<qual é o trabalho dele; por que ele nunca fala com o banco; como ele chama a API>
+<feche com quem depende de quem, e o que quebra quando o contrato entre os dois muda>
+
+## Os arquivos que você não escreveu
+| Arquivo ou pasta | Para que serve | Quando você vai mexer nele |
+(só os que importam: o `package.json` da raiz e o de cada app, a configuração do
+runner de teste, `.gitignore`, `.gitattributes`, `.github/`)
+
+## Por que a suíte nasce verde e vazia
+<o que um teste que passa sem testar nada prova de fato; e por que isso é
+pré-requisito do RED da primeira tarefa — um teste vermelho só é informação num
+repositório onde os testes comprovadamente rodam>
+
+## Três perguntas de professor
+1. ...
+(sem as respostas)
+
+## Para pesquisar
+<2 a 4 termos exatos>
+```
+
 ---
 
 > ⚠️ Você existe para o aluno chegar à defesa **sem precisar de você**. Nunca entregue texto pronto para ele colar no PR ou decorar — entregue entendimento.

.agents/rules/utf-rules.md

@@ -8,15 +8,15 @@ Você é um agente de IA atuando como equipe de execução. O usuário (aluno) 
 
 ## 1. Fases Estritas do Spec-Driven Development (SDD)
 - Você está proibido de pular etapas. O ciclo é: Entendimento -> Planejamento -> Execução -> Revisão.
-- Sempre que o usuário pedir para trabalhar em uma Issue (ou usar `/utf-issue <n>`), leia e execute `.agents/workflows/utf-workflow.md`. A execução de cada tarefa do plano segue `.agents/workflows/ciclo-tarefa.md` (`/utf-task <n>`).
+- Sempre que o usuário pedir para trabalhar em uma Issue (ou usar `/utf-issue <n>`), leia e execute `.agents/workflows/utf-issue.md`. A execução de cada tarefa do plano segue `.agents/workflows/utf-task.md` (`/utf-task <n>`).
 - **PROIBIDO CODIFICAR CEDO:** Nunca gere código funcional (TypeScript, HTML, CSS, etc.) sem antes conduzir um brainstorming e ter os artefatos `spec.md` e `plan.md` salvos e aprovados explicitamente pelo usuário.
 - Exceção única: o scaffold do `/utf-setup`, que não contém regra de negócio nem entidade do PRD — é Task de manutenção, sem spec.
 
 ## 2. Limites do Ciclo (as duas rodadas)
 Existem **dois contadores diferentes**, aninhados. Eles não se somam e não se substituem:
 
 - **Rodada de TDD** — vive dentro do implementador. Se o mesmo teste falhar duas vezes seguidas pelo mesmo motivo, ele PARA e relata. Não tenta uma terceira abordagem.
-- **Rodada de revisão** — vive no fluxo `ciclo-tarefa`. Uma rodada é uma passada inteira: implementar → revisar → triagem do usuário. Havendo apontamento aceito na segunda, o fluxo PARA e escala. **Não existe rodada 3.**
+- **Rodada de revisão** — vive no fluxo `/utf-task`. Uma rodada é uma passada inteira: implementar → revisar → triagem do usuário. Havendo apontamento aceito na segunda, o fluxo PARA e escala. **Não existe rodada 3.**
 
 Ao estourar qualquer um dos dois, PARE IMEDIATAMENTE e diga qual estourou: "Estourei o limite de 2 rodadas de TDD" ou "de revisão". Há algo errado com a premissa ou o contexto — quem analisa é o usuário. Não entre em loops de refatoração infinitos.
 

.agents/workflows/architecture.md → .agents/workflows/utf-architecture.md

@@ -15,6 +15,12 @@ Você é o entrevistador técnico. O aluno é o Arquiteto: **ele decide; você a
 
 ## Passo 0 — Pré-condições
 
+0. **O documento anterior está commitado.** Rode `git status --porcelain docs/user-flows.md docs/design-tokens.md`:
+   se a saída **não** estiver vazia, ou se o arquivo não estiver versionado, **PARE** e
+   peça o commit ao aluno. Não é burocracia: cada documento da Fase 0 é decisão dele, e
+   o commit é o que põe o nome dele nessa decisão. Seguir sem commitar empilha quatro
+   documentos num commit só, no fim, e a autoria some.
+
 0. `docs/user-flows.md` tem pelo menos uma jornada desenhada, com o parágrafo de decisão sobre o nó vermelho. Se não tiver, **PARE** e mande rodar `/utf-flows`: é lá que aparecem os estados que faltam ("o pedido fica AGUARDANDO para sempre?"), e estado esquecido aqui vira retrabalho na primeira spec.
 1. `docs/prd.md` existe, com glossário, atores e stories. Sem ele, **PARE**: este documento responde *onde moram* as coisas que o PRD nomeia — sem PRD não há o que mapear. Mande rodar `/utf-prd` antes.
 2. Leia `docs/checklist.md` **inteiro** — a seção *Regras da disciplina* diz o que é stack fixa e o que é escolha do aluno, e vários IDs são padrões estruturais que este documento precisa declarar.
@@ -43,6 +49,7 @@ Antes de fechar, confira que o documento declara **explicitamente** as quatro co
 
 1. Percorra o `docs/checklist.md` e confira o documento contra **todo ID que dependa de uma declaração de arquitetura** — o que faltar vira pergunta, não texto inventado.
 2. Grave `docs/architecture.md`. **PARE.** O aluno lê fora do chat; o commit é dele. Próximo passo: `/utf-setup`.
+   Este é o documento mais técnico da Fase 0, e o aluno acabou de decidir coisas que talvez não conheça. Ofereça, sem enfeite: *"Antes de commitar, rode `/utf-tutor architecture` — ele explica monorepo, camadas, ORM e o diagrama ER em cima das suas escolhas, não em exemplo genérico."*
 
 ## Proibições
 

.agents/workflows/user-flows.md → .agents/workflows/utf-flows.md

@@ -27,6 +27,12 @@ fechado.
 
 ## Passo 0 — Pré-condições
 
+0. **O documento anterior está commitado.** Rode `git status --porcelain docs/prd.md`:
+   se a saída **não** estiver vazia, ou se o arquivo não estiver versionado, **PARE** e
+   peça o commit ao aluno. Não é burocracia: cada documento da Fase 0 é decisão dele, e
+   o commit é o que põe o nome dele nessa decisão. Seguir sem commitar empilha quatro
+   documentos num commit só, no fim, e a autoria some.
+
 1. `docs/prd.md` preenchido, com stories e critérios de aceite. Sem ele, **PARE** e
    mande rodar `/utf-prd` — jornada sem história é desenho decorativo.
 2. Se `docs/user-flows.md` já tem jornada real (não é esqueleto), **PARE** e pergunte:
@@ -115,6 +121,7 @@ registre como pendência — não invente cor nem link.
 
 1. Grave `docs/user-flows.md` e `docs/design-tokens.md`.
 2. **PARE.** O aluno lê fora do chat. O commit é dele.
+   Ofereça: *"Rode `/utf-flows` de novo se quiser outra jornada, ou `/utf-tutor flows` se quiser entender por que o nó vermelho muda o sistema."*
 3. Próximo passo: `/utf-architecture` — que vai ler as jornadas para encontrar os
    estados e os pontos de decisão que o `architecture.md` precisa declarar.
 

.agents/workflows/utf-workflow.md → .agents/workflows/utf-issue.md

@@ -48,13 +48,13 @@ status: rascunho   # rascunho | aprovada
 - Aprovado, proponha o commit do plano (`plan: <slug> (#<n>)`) e faça-o com o OK do usuário. Spec e plano são os primeiros commits da branch, **antes de qualquer código** — é o `git log` que prova que a especificação veio primeiro.
 
 **Passo 3: Execução (uma tarefa por vez)**
-- Execute **uma tarefa por vez** através do fluxo `ciclo-tarefa` (`.agents/workflows/ciclo-tarefa.md`), que despacha o subagente **implementador** com contexto limpo e, depois dele, dois revisores distintos e somente-leitura: **revisor-conformidade** (diff × critérios de aceite da `spec.md`) e **revisor-codigo** (diff × `docs/architecture.md`).
+- Execute **uma tarefa por vez** através do fluxo `/utf-task` (`.agents/workflows/utf-task.md`), que despacha o subagente **implementador** com contexto limpo e, depois dele, dois revisores distintos e somente-leitura: **revisor-conformidade** (diff × critérios de aceite da `spec.md`) e **revisor-codigo** (diff × `docs/architecture.md`).
 - **Você nunca revisa o código que você mesmo despachou.** Revisor é sempre outro agente, sem permissão de escrita. Auto-auditoria não conta como revisão: quem escreveu carrega os mesmos pontos cegos.
 - Ao fim de cada tarefa, pare e devolva o controle ao usuário. Ele pede a próxima.
 
 **Passo 4: Auditoria final e Pull Request**
 - Terminadas todas as tarefas, atualize **primeiro** a documentação: o status da história no `docs/prd.md` (→ `Live`), os diagramas do `docs/architecture.md` que mudaram, e a linha da spec no `specs/README.md` (→ `implementada`). Proponha o commit e faça-o **só com o "pode commitar" do usuário** — o portão do commit vale aqui como em cada tarefa.
-- Despache então o subagente **auditor-final**, que compara o diff **inteiro** da branch contra o `spec.md` original — nunca contra o `plan.md` — e confere a documentação que acabou de ser atualizada. Se o veredito for NÃO PRONTO, cada pendência vira tarefa nova no `plan.md` (com o OK do usuário) e passa pelo `ciclo-tarefa`; depois o auditor roda de novo.
+- Despache então o subagente **auditor-final**, que compara o diff **inteiro** da branch contra o `spec.md` original — nunca contra o `plan.md` — e confere a documentação que acabou de ser atualizada. Se o veredito for NÃO PRONTO, cada pendência vira tarefa nova no `plan.md` (com o OK do usuário) e passa pelo `/utf-task`; depois o auditor roda de novo.
 - Com PRONTO PARA PR, sugira `/utf-tutor prova` — o simulado interativo sobre o diff inteiro, que é o ensaio da defesa presencial.
 - Lembre o usuário de abrir o Pull Request com `Closes #<n>`.
 - A seção **"O que este PR faz e por quê"** é escrita **pelo usuário, com as palavras dele**. Ofereça os fatos do diff; não ofereça o texto pronto.

.agents/workflows/prd.md → .agents/workflows/utf-prd.md

@@ -48,6 +48,7 @@ Percorra o `docs/checklist.md` e confira o rascunho contra **todo ID cuja sement
 
 1. Grave `docs/prd.md` completo.
 2. **PARE.** O aluno lê o documento inteiro, fora do chat. Ajuste agora custa uma conversa; depois, custa uma spec.
+   Ofereça, com estas palavras: *"Se algum termo do documento for novo — user story, critério de aceite, MoSCoW, glossário ubíquo — rode `/utf-tutor prd` antes de commitar, que eu explico cada um em cima do seu documento."*
 3. O commit do `prd.md` é **dele**. Próximos passos, nesta ordem: com o **aceite do professor** e stories `Ready`, `/utf-backlog` leva as stories para o GitHub (Issues + Kanban); depois `/utf-flows`, que desenha as jornadas e acha os pontos de desistência; e só então `/utf-architecture`.
 
 ## Proibições

.agents/workflows/setup.md → .agents/workflows/utf-setup.md

@@ -14,6 +14,12 @@ que foi decidida. O que não estiver escrito lá, você pergunta; não escolhe.
 
 ## Passo 0 — Pré-condições (PARE se qualquer uma falhar)
 
+0. **Os documentos da Fase 0 estão commitados.** Rode
+   `git status --porcelain docs/`: se a saída **não** estiver vazia, **PARE** e peça
+   o commit. O scaffold vai nascer a partir do `architecture.md`; se ele ainda não
+   está no histórico, o repositório não tem como provar qual decisão gerou qual
+   arquivo — e é essa rastreabilidade que a avaliação cobra.
+
 1. `docs/prd.md` e `docs/architecture.md` existem e declaram: o framework do backend,
    o framework do frontend, a estrutura de pastas do monorepo e como rodar os testes.
    Se algum desses quatro estiver ausente ou ambíguo, **PARE** e diga o que falta —
@@ -154,12 +160,18 @@ motivo, **PARE** e relate. Não tente uma terceira abordagem.
 1. Commits pequenos e nomeados por passo (apps, raiz, ferramentas do método) —
    **cada um proposto ao usuário antes** ("commit do passo X: <mensagem>?"),
    nenhum sem o OK dele.
-2. Relate ao usuário: o que foi gerado, a saída dos testes, e as decisões que o
+2. **Despache o tutor em modo `setup`, antes do PR.** Este é o único momento do
+   semestre em que o aluno recebe um monte de arquivos que ele não escreveu e não
+   viu nascer — se ninguém explicar, ele abre o primeiro PR sem saber o que tem
+   dentro do próprio repositório. Não pergunte se ele quer: despache, apresente a
+   explicação na íntegra e só então siga. O despacho leva `docs/architecture.md`, a
+   lista de arquivos gerados e a saída dos testes.
+3. Relate ao usuário: o que foi gerado, a saída dos testes, e as decisões que o
    `architecture.md` não cobria (Passo 2) para ele ratificar no documento.
    **Ratificação aprovada pelo usuário = atualize o `architecture.md` na mesma
    branch**, antes do PR — documento e scaffold entram juntos, contando a mesma
    história.
-3. Instrua o usuário a abrir o PR com a etiqueta **`manutencao`** — setup é Task,
+4. Instrua o usuário a abrir o PR com a etiqueta **`manutencao`** — setup é Task,
    não história. O corpo já vem preenchido pelo
    `.github/pull_request_template.md`, que está na `main` desde o template.
    Explique o detalhe que ninguém adivinha:

.agents/workflows/ciclo-tarefa.md → .agents/workflows/utf-task.md

@@ -94,7 +94,7 @@ Havendo apontamentos, **quem decide o destino de cada um é o usuário, não voc
 
 | Situação | O que fazer |
 | --- | --- |
-| Ambos **APROVADO**, ou **todos os apontamentos recusados** na triagem | **PAUSA OBRIGATÓRIA — nada de commit ainda.** Apresente ao usuário: o resumo do diff (arquivos e o que mudou em cada um), o veredito dos dois revisores e o convite para **conferir o diff na IDE** com o roteiro que o tutor deu no Passo 1. Revisor aprovar não substitui o olho do dono: **espere o aceite explícito** ("pode commitar"). Só então marque a tarefa como feita no `plan.md` (`- [x]`) e faça o commit (incluindo pareceres e decisões) com a mensagem começando por `tarefa $1: ` — é essa convenção que permite ao `/utf-tutor $1` achar o diff. **Depois do commit**, ofereça `/utf-tutor $1` para a aula sobre o diff — antes dele o tutor não tem commit para localizar. Feche o relato com a **listinha das tarefas restantes** do `plan.md` (número e título, na ordem), dizendo qual é a próxima — ou, se não restar nenhuma, que o plano acabou e que `/utf-issue <n>` retoma no fechamento (auditor final e PR). Espere ele pedir a próxima (`/utf-task` sem número já a pega). |
+| Ambos **APROVADO**, ou **todos os apontamentos recusados** na triagem | **PAUSA OBRIGATÓRIA — nada de commit ainda.** Apresente o veredito dos dois revisores e, **antes de pedir o aceite**, despache o tutor em modo `passo` e conduza a leitura do diff **um arquivo por vez**, esperando o usuário a cada arquivo. É aqui que ele aprende a sintaxe, com a mudança fresca e pequena — o implementador escreve rápido demais para alguém acompanhar, e sem esta parada o aluno chega ao PR sem ter lido nada. Ele pode dispensar (*"pode pular a leitura"*), e aí você segue direto; **não pule por conta própria**. Convide-o a acompanhar pelo diff na IDE, com o roteiro que o tutor deu no Passo 1. Revisor aprovar não substitui o olho do dono: **espere o aceite explícito** ("pode commitar"). Só então marque a tarefa como feita no `plan.md` (`- [x]`) e faça o commit (incluindo pareceres e decisões) com a mensagem começando por `tarefa $1: ` — é essa convenção que permite ao `/utf-tutor $1` achar o diff. **Depois do commit**, ofereça `/utf-tutor $1` para a aula sobre o diff — antes dele o tutor não tem commit para localizar. Feche o relato com a **listinha das tarefas restantes** do `plan.md` (número e título, na ordem), dizendo qual é a próxima — ou, se não restar nenhuma, que o plano acabou e que `/utf-issue <n>` retoma no fechamento (auditor final e PR). Espere ele pedir a próxima (`/utf-task` sem número já a pega). |
 | Algum apontamento **aceito**, rodada de revisão 1 | Volte ao Passo 2 com um implementador novo (sem repetir o tutor), transcrevendo **apenas os apontamentos aceitos**. |
 | Algum apontamento **aceito**, rodada de revisão 2 | **PARE. Não existe rodada 3.** |