Manutencao/paridade com sdd

.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">
 
@@ -124,3 +130,111 @@ O gabarito é para quem conduz o simulado, **não** para o aluno ver antes de re
 ---
 
 > ⚠️ Você existe para o aluno chegar à defesa **sem precisar de você**. Nunca entregue texto pronto para ele colar no PR ou decorar — entregue entendimento.
+
+## 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 `inject()`, um `signal()`, 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 `carregar`
+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 `app.config.ts`, um export, uma rota) 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`, `design` 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 | tokens de design | 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 o gerador criou, e por que essa forma
+<o que o `ng new` monta: a árvore de pastas, o componente raiz, o bootstrap em
+`main.ts` e a configuração em `app.config.ts`; o que muda em relação a abrir um
+`index.html` na mão>
+
+## O app e a fonte de dados
+### O app `apps/web` — Angular <versão lida do architecture.md>
+<qual é o trabalho dele; o caminho de um dado da rota até a tela; onde as regras vão morar>
+### A fonte de dados — <json-server ou o BaaS declarado>
+<por que este projeto não tem backend próprio; o que o BaaS entrega pronto
+(autenticação, banco, API) e o que continua sendo responsabilidade do app;
+o que a pasta `apps/api`, reservada e vazia, está guardando lugar para>
+<feche com o que quebra no app quando o contrato da fonte de dados 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`, `angular.json`, `tsconfig.json`, 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>
+```

.agents/workflows/utf-architecture.md

@@ -15,9 +15,14 @@ Você é o entrevistador técnico. O aluno é o Arquiteto: **ele decide; você a
 
 ## Passo 0 — Pré-condições
 
-0. `docs/design-tokens.md` tem os tokens, os breakpoints e a identidade PWA, e o link público do protótipo está registrado. Se não tiver, **PARE** e mande rodar `/utf-design`: o protótipo e as decisões de abandono revelam estados e telas que este documento precisa mapear — descobri-los depois é 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.
+0. **Os documentos anteriores estão commitados.** Rode
+   `git status --porcelain docs/prd.md docs/design-tokens.md`: se a saída **não** estiver
+   vazia, ou se algum deles não estiver versionado, **PARE** e peça o commit ao aluno.
+   O commit é o que põe o nome dele na decisão; sem ele a autoria da Fase 0 some num
+   commit único no fim.
+1. `docs/design-tokens.md` tem os tokens, os breakpoints e a identidade PWA, e o link público do protótipo está registrado. Se não tiver, **PARE** e mande rodar `/utf-design`: o protótipo e as decisões de abandono revelam estados e telas que este documento precisa mapear — descobri-los depois é retrabalho na primeira spec.
+2. `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.
+3. 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.
 
 ## Passo 1 — As decisões, uma por vez
 
@@ -43,6 +48,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 standalone, injeção de dependência, signals e o modelo de dados do BaaS em cima das suas escolhas, não em exemplo genérico."*
 
 ## Proibições
 

.agents/workflows/utf-backlog.md

@@ -15,7 +15,9 @@ fica velha, e a IA lê a versão errada.
    (`gh auth status`). Sem um dos dois, **PARE** e oriente: instalar o `gh`,
    `gh auth login`, escopos `repo` e `project`.
 2. `docs/prd.md` preenchido e **commitado pelo aluno**, com o tema já
-   **aceito pelo professor**.
+   **aceito pelo professor**. Confira o commit com
+   `git status --porcelain docs/prd.md`: saída não vazia significa que ainda há
+   alteração pendente — **PARE** e peça o commit antes de criar Issue nenhuma.
 3. Existe ao menos uma story com `Status: Ready`. Story `Draft` não vira
    Issue — regra indefinida não entra na fila de implementação.
 

.agents/workflows/utf-design.md

@@ -19,6 +19,11 @@ não consegue guardar — os tokens, os breakpoints e as decisões de abandono.
 
 ## 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 os
+   documentos num commit só, no fim, e a autoria some.
 1. `docs/prd.md` preenchido, com stories e critérios. Sem ele, **PARE** e mande
    rodar `/utf-prd` — design sem requisito é decoração.
 2. Se `docs/design-tokens.md` já tem conteúdo real, **PARE** e pergunte: revisar ou
@@ -60,6 +65,8 @@ vira documento novo — vira **regra de negócio ou critério de aceite no `prd.
    link do protótipo).
 2. **PARE.** A equipe revisa fora do chat; o commit é dela. Próximo passo:
    `/utf-architecture`.
+   Ofereça: *"Rode `/utf-tutor design` se quiser entender por que nome semântico de cor,
+   escala de espaçamento e estados de botão mudam o que a IA vai gerar em cada tela."*
 
 ## Proibições
 

.agents/workflows/utf-issue.md

@@ -9,12 +9,13 @@ Sempre que o usuário pedir para trabalhar em uma Issue (Feature), você atuará
 **Passo 0: Pré-condições**
 - Acesso ao GitHub: MCP do GitHub disponível **ou** `gh` autenticado (`gh auth status`). Sem um dos dois, **PARE** — este fluxo lê Issues e prepara PR.
 - A Issue existe no GitHub. Se as Issues das stories ainda não foram criadas, mande rodar `/utf-backlog` primeiro.
+- **Retomada.** Se `specs/<numero-da-issue>-<slug>/` já existe, **não recomece**: descubra o estado e entre no passo certo — spec `rascunho` → a pausa do Passo 1, esperando a aprovação; `aprovada` sem `plan.md` → Passo 2; plano com tarefa pendente → Passo 3; todas as tarefas feitas → Passo 4. É assim que `/utf-issue <n>` fecha a Issue depois da última tarefa, e é o que impede reescrever uma spec que o usuário já aprovou.
 
 **Passo 1: Entendimento e Brainstorming**
 - Leia a Issue apontada e busque no `docs/prd.md` os critérios e o Glossário Ubíquo.
 - Faça perguntas ao usuário de forma proativa. Questione sobre casos de borda, caminhos tristes (ex: falhas de rede, dados inválidos) e como validar os critérios de aceite.
 - Após sanar as dúvidas, **crie a branch da história a partir da `develop`** (`git switch develop && git pull && git switch -c <numero-da-issue>-<slug>`). Ela nasce agora, antes da aprovação, porque no Gitflow `main` e `develop` são bloqueadas — e o commit de aprovação do usuário precisa de um lugar para viver.
-- Redija o documento e salve no caminho `specs/<numero-da-issue>-<slug>/spec.md`, commitando o rascunho na branch, com este frontmatter:
+- Redija o documento e salve no caminho `specs/<numero-da-issue>-<slug>/spec.md`, commitando o rascunho na branch. **A estrutura é a de `docs/modelo-spec.md`** — copie-a e preencha; os comentários dela explicam cada seção e são apagados no caminho. Não invente seções novas nem pule as existentes. O frontmatter:
 
 ```yaml
 ---
@@ -29,7 +30,7 @@ status: rascunho   # rascunho | aprovada
 - Com o `spec.md` aprovado, quebre o trabalho em tarefas curtas e encadeadas — cada uma prova **um critério de aceite inteiro**, ou é um passo técnico que sozinho não prova nada mas destrava o próximo.
 - Cada tarefa deve prever a criação de testes primeiro (TDD).
 - Se o plano passar de **10 tarefas**, pare: a história é grande demais. Proponha dividi-la em duas Issues antes de continuar.
-- Salve o resultado no caminho `specs/<numero-da-issue>-<slug>/plan.md`.
+- Salve o resultado no caminho `specs/<numero-da-issue>-<slug>/plan.md`, na forma de `docs/modelo-plan.md`: checklist `- [ ] **Tarefa N — <título>**`, cada uma citando o critério de aceite que cobre e o teste que nasce primeiro. Tarefa feita vira `- [x]`: é essa marcação que o `/utf-task` sem número lê. A seção *Critérios sem tarefa* precisa terminar vazia.
 - **PAUSA OBRIGATÓRIA:** Peça a aprovação do usuário para o plano. Com o OK, commite o `plan.md` na branch da história.
 
 **Passo 3: Execução (uma tarefa por vez)**
@@ -39,8 +40,8 @@ status: rascunho   # rascunho | aprovada
 - 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, despache o subagente **auditor-final**, que compara o diff **inteiro** contra o `spec.md` original — nunca contra o `plan.md`.
-- Atualize, no mesmo commit do comportamento: o status da história no `docs/prd.md`, os diagramas do `docs/architecture.md` que mudaram, e o `specs/README.md`.
+- Terminadas todas as tarefas, atualize **primeiro** a documentação: o status da história no `docs/prd.md`, os diagramas do `docs/architecture.md` que mudaram, e a linha da spec no `specs/README.md`. 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** contra o `spec.md` original — nunca contra o `plan.md` — e confere a documentação que acabou de ser atualizada. Auditar antes de atualizar os documentos é auditar um repositório que ainda não é o que vai para o PR. 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.
 - Antes de o usuário escrever o PR, sugira `/utf-tutor prova` — o simulado interativo sobre o diff inteiro, que é o ensaio da defesa presencial.
 - Prepare as alterações (commit) e 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/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-design`, que fecha tokens, protótipo e os pontos de desistência; e só então `/utf-architecture`.
 
 ## Proibições

.agents/workflows/utf-setup.md

@@ -14,6 +14,11 @@ 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
    frontend (versão e padrões), a fonte de dados de cada fase, a estrutura de
    pastas e como rodar os testes.
@@ -171,12 +176,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: