fix: revisão de consistência — Gitflow completo, portão de 400, resto…

.agents/agents/auditor-final.md

@@ -1,6 +1,6 @@
 ---
 name: auditor-final
-description: Passo 6 do ciclo. Compara o diff INTEIRO da branch contra a spec.md original, não contra o plano. Somente leitura.
+description: Passo 6 do guia (§4). Compara o diff INTEIRO da branch contra a spec.md original, não contra o plano. Somente leitura.
 mainAgent: false
 subagent: true
 tools:
@@ -29,7 +29,7 @@ Você não altera nenhum arquivo.
 
 1. Leia o `spec.md` **original**, incluindo as seções *fora de escopo*, *abandono no meio* e *assume que*.
 2. **Ignore o `plan.md`.** Ele é meio, não fim — se o plano omitiu um critério, comparar contra ele esconde exatamente o defeito que você procura.
-3. Leia o diff completo da branch contra a `main` (comando vem no despacho).
+3. Leia o diff completo da branch contra a `develop` (comando vem no despacho — no Gitflow a feature branch nasce da `develop`).
 4. Rode a suíte de testes inteira, não só os testes novos.
 5. Confira, um a um, **todos** os critérios de aceite da spec.
 

.agents/agents/revisor-codigo.md

@@ -33,8 +33,8 @@ Caminho do `spec.md`, número e texto da tarefa, e o comando de diff vêm no des
 
 ## O que reprova
 
-- violação de camada declarada no `architecture.md` (ex.: controller acessando o banco direto)
-- resposta de API fora do formato global (envelope, `statusCode`, `message`)
+- violação de camada declarada no `architecture.md` (ex.: componente chamando o `HttpClient` direto, sem passar pelo Service)
+- sintaxe fora dos padrões declarados no `architecture.md` (ex.: `*ngIf` no lugar de `@if`, injeção por construtor no lugar de `inject()`, estado fora de signals)
 - segredo, chave ou URL de ambiente escrita no código
 - tratamento de erro que engole a falha silenciosamente
 - abstração criada para um caso só — indireção sem ganho

.agents/agents/tutor.md

@@ -24,8 +24,8 @@ Você não implementa, não corrige e não avalia qualidade — quem aponta prob
 ## Regras didáticas (valem para todos os modos)
 
 - **Português simples, um conceito por vez.** Frases curtas. Nada de jargão sem definição na primeira aparição.
-- **Nomeie o termo oficial** (em inglês, como aparece na documentação) para o aluno conseguir pesquisar sozinho: "isso se chama *dependency injection*", "esse decorator é um *Guard*".
-- **Explique o porquê do framework, não só o quê.** Não "criei um service", mas *por que o Nest injeta o service em vez de dar `new`, e o que quebraria sem isso*.
+- **Nomeie o termo oficial** (em inglês, como aparece na documentação) para o aluno conseguir pesquisar sozinho: "isso se chama *dependency injection*", "essa função passada à rota é um *Functional Guard*".
+- **Explique o porquê do framework, não só o quê.** Não "criei um service", mas *por que o Angular injeta o service via `inject()` em vez de dar `new`, e o que quebraria sem isso*.
 - **Use analogia do dia a dia** quando ela tornar o mecanismo visível (ex.: o Guard é a portaria do prédio: decide se a visita sobe antes de o morador atender).
 - **Ancore no projeto do aluno**, não em exemplos genéricos: cite os arquivos, entidades e rotas reais dele.
 - **Ligue aos Indicadores da disciplina** quando pertinente — os IDs estão em `docs/checklist.md`; cite o número e o que a tarefa evidencia dele.
@@ -78,9 +78,9 @@ Devolva:
 ```
 # Tutor — Tarefa <n> explicada
 
-## O caminho da requisição
-<o que o código faz, em português, seguindo a requisição de ponta a ponta:
-rota → pipe/guard → controller → service → banco → resposta (o que existir no diff)>
+## O caminho do dado
+<o que o código faz, em português, seguindo o dado de ponta a ponta:
+rota → guard/resolver → componente → service → HTTP/interceptor → BaaS → signal → tela (o que existir no diff)>
 
 ## Por que o framework faz assim
 <para cada mecanismo do diff: o motivo do desenho e o que quebraria sem ele>

.agents/workflows/ciclo-tarefa.md

@@ -1,5 +1,5 @@
 ---
-description: Executa UMA tarefa do plan.md com o ciclo completo do Passo 5 — tutor explica antes e o usuário aceita, implementador com contexto limpo, dois revisores distintos e somente-leitura, máximo de 2 rodadas de revisão. Recebe o número da tarefa; sem número, resolve a próxima pendente do plan.md.
+description: Executa UMA tarefa do plan.md com o ciclo completo do Passo 5 do guia (§4) — tutor explica antes e o usuário aceita, implementador com contexto limpo, dois revisores distintos e somente-leitura, máximo de 2 rodadas de revisão. Recebe o número da tarefa; sem número, resolve a próxima pendente do plan.md.
 ---
 
 # Ciclo de uma tarefa
@@ -13,7 +13,7 @@ Tarefa a executar: **$1**
 ## Passo 0 — Localizar e travar
 
 1. Descubra a pasta `specs/<issue>-<slug>/` da branch atual.
-2. Abra o `spec.md` e confira `status: aprovada` no frontmatter. **Se não estiver, PARE** e diga: *"A spec ainda não foi aprovada por você. O portão do Passo 3 não passou."*
+2. Abra o `spec.md` e confira `status: aprovada` no frontmatter. **Se não estiver, PARE** e diga: *"A spec ainda não foi aprovada por você. O portão de aprovação da spec (Passo 3 do guia) não passou."*
 3. **Se o comando veio sem número**, resolva-o pelo `plan.md`: a tarefa é a **primeira ainda não marcada como feita**, na ordem do plano. Anuncie ao usuário qual número foi resolvido (ex.: *"Próxima pendente: tarefa 3 — <título>"*) antes de seguir — daqui em diante, esse número é o `$1` em tudo (pareceres, decisões, commit). **Se não houver nenhuma pendente, PARE** e diga: *"Não há mais tarefas pendentes no `plan.md`. O próximo passo é o auditor final e o Pull Request, pelo fluxo da Issue."* Não invente tarefa nova.
 4. Extraia do `plan.md` o **texto literal** da tarefa `$1`.
 5. Guarde o ponto de partida: `git rev-parse HEAD`. Ele é a base de todos os diffs desta tarefa.

.agents/workflows/setup.md

@@ -14,12 +14,15 @@ 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)
 
-1. `docs/prd.md` e `docs/architecture.md` existem e declaram: o framework do backend,
-   o framework do frontend, a fonte de dados, a estrutura de pastas e como rodar os testes.
+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.
    Se algum desses quatro estiver ausente ou ambíguo, **PARE** e diga o que falta —
    setup com stack adivinhada é retrabalho garantido.
 2. As pastas de app previstas no `architecture.md` (ex.: `apps/web`)
-   **não existem** ou estão vazias. Se já existirem com conteúdo, **PARE**: o setup
+   **não existem** ou estão vazias — o `.gitkeep` de `apps/web/` e o `README.md`
+   de reserva de `apps/api/`, que vêm do template, não contam como conteúdo.
+   Se já existirem com conteúdo de verdade, **PARE**: o setup
    roda uma vez, e rodá-lo de novo por cima é destrutivo.
 3. Você está na `develop`, limpa e atualizada (se a `develop` ainda não existe, crie-a a partir da `main` e publique: `git switch -c develop && git push -u origin develop` — o Gitflow da ficha exige as duas).
 4. O `gh` está autenticado (`gh auth status`) **ou** o MCP do GitHub está
@@ -42,9 +45,10 @@ Gere o app com o gerador oficial da stack declarada no `architecture.md`
 dentro da estrutura de pastas que o documento descreve.
 
 - **A casca do monorepo é só estrutura.** Se o documento prevê `apps/web` e
-  `apps/api`, gere o app em `apps/web` e **crie `apps/api/` vazia**, com um
-  `README.md` de uma linha dizendo que ela está reservada para uma API própria,
-  se um dia existir. **Não gere backend nenhum** — nem scaffold, nem
+  `apps/api`, gere o app em `apps/web` (o `.gitkeep` que veio do template pode
+  ser removido junto) e **confira `apps/api/`**: ela vem do template com um
+  `README.md` de uma linha dizendo que está reservada para uma API própria,
+  se um dia existir — crie-a assim se faltar. **Não gere backend nenhum** — nem scaffold, nem
   `package.json`, nem dependência. Pasta reservada é lugar guardado; scaffold
   morto é código que ninguém mantém e que o agente lê como se existisse.
 
@@ -114,7 +118,7 @@ do guia é exatamente como o Portão nasce parafraseado e sem efeito.
    ```
    gh api -X PUT repos/{owner}/{repo}/branches/main/protection --input - <<'JSON'
    {
-     "required_status_checks": null,
+     "required_status_checks": { "strict": false, "checks": [ { "context": "explicacao" } ] },
      "enforce_admins": true,
      "required_pull_request_reviews": { "required_approving_review_count": 1 },
      "restrictions": null,
@@ -127,7 +131,10 @@ do guia é exatamente como o Portão nasce parafraseado e sem efeito.
    `required_approving_review_count: 1` exige **Pull Request aprovado por um
    colega** — nesta disciplina o projeto é em equipe (2–3), e a revisão entre
    colegas com resolução de conflitos é cobrada pelo ID27: quem abre a story
-   não mergeia o próprio PR. `enforce_admins: true` faz a regra valer também para o
+   não mergeia o próprio PR. O bloco `required_status_checks` exige que o check
+   `explicacao` (o job do Portão de Entendimento) **passe antes do merge** — sem
+   ele, o Portão reprovaria mas não bloquearia nada.
+   `enforce_admins: true` faz a regra valer também para o
    dono do repositório: sem isso, o aluno é justamente quem fura a regra sem
    perceber. Para destravar uma emergência ele desliga a proteção
    conscientemente, e isso fica registrado no log do repositório.

.agents/workflows/tutor.md

@@ -26,7 +26,7 @@ Sem argumento, pergunte ao usuário qual modo ele quer.
 3. Conforme o modo, acrescente:
    - **`depois`**: número e texto literal da tarefa, e o comando de diff. Encontre o commit da tarefa com `git log --oneline --grep "tarefa <n>"` (convenção de commit do ciclo-tarefa) e monte `git diff <sha>^..<sha>`. Se a tarefa tiver mais de um commit ou o commit não for encontrado, monte o intervalo à mão e confirme com o usuário antes de despachar.
    - **`antes`**: número e texto literal da tarefa, e os critérios de aceite ligados a ela, transcritos.
-   - **`prova`**: o comando do diff completo da branch: `git diff main..HEAD`.
+   - **`prova`**: o comando do diff completo da branch: `git diff develop..HEAD` (no Gitflow a feature branch nasce da `develop` — diff contra a `main` traria trabalho de outras histórias já integradas).
 
 ## Entregar
 

.agents/workflows/utf-workflow.md

@@ -13,7 +13,8 @@ Sempre que o usuário pedir para trabalhar em uma Issue (Feature), você atuará
 **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, redija o documento e salve no caminho `specs/<numero-da-issue>-<slug>/spec.md`, com este frontmatter:
+- 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:
 
 ```yaml
 ---
@@ -22,17 +23,17 @@ status: rascunho   # rascunho | aprovada
 ---
 ```
 
-- **PAUSA OBRIGATÓRIA:** Pare de gerar respostas e exija que o usuário leia e aprove o `spec.md`. Ofereça `/utf-tutor spec` para ele entender as consequências técnicas de cada decisão antes de aprovar. A aprovação é o **próprio usuário** trocar `status: rascunho` por `status: aprovada` e commitar essa linha — assim a aprovação fica no `git log`, com o nome dele. Você não altera esse campo em hipótese nenhuma.
+- **PAUSA OBRIGATÓRIA:** Pare de gerar respostas e exija que o usuário leia e aprove o `spec.md`. Ofereça `/utf-tutor spec` para ele entender as consequências técnicas de cada decisão antes de aprovar. A aprovação é o **próprio usuário** trocar `status: rascunho` por `status: aprovada` e commitar essa linha **na branch da história** — assim a aprovação fica no `git log`, com o nome dele. Você não altera esse campo em hipótese nenhuma.
 
 **Passo 2: Planejamento**
-- Com o `spec.md` aprovado, quebre o trabalho em tarefas curtas e encadeadas (2 a 5 minutos cada).
+- 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`.
-- **PAUSA OBRIGATÓRIA:** Peça a aprovação do usuário para o plano.
+- **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)**
-- Crie a branch da Issue a partir da `develop` (Gitflow — ver a ficha).
+- A branch da história existe desde o Passo 1. Antes do primeiro código, confira que o `spec.md` (aprovado) e o `plan.md` estão commitados nela — é esse `git log` que prova que a especificação veio antes do código.
 - 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`).
 - **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.

.claude/commands/utf-tutor.md

@@ -5,4 +5,4 @@ argument-hint: <n | antes <n> | spec | prova>
 
 Leia `.agents/workflows/tutor.md` e execute-o integralmente.
 
-Argumento: $1
+Argumento: $ARGUMENTS

.github/workflows/portao-de-entendimento.yml

@@ -15,7 +15,8 @@ jobs:
           TEXTO=$(printf '%s' "$CORPO" \
             | sed -n '/O que este PR faz e por quê/,$p' \
             | tail -n +2 \
-            | sed '/^##/,$d')
+            | sed '/^##/,$d' \
+            | perl -0pe 's/<!--.*?-->//gs')
           TAMANHO=$(printf '%s' "$TEXTO" | tr -d '[:space:]' | wc -c)
           echo "Caracteres na explicação: $TAMANHO (mínimo 400)"
           if [ "$TAMANHO" -lt 400 ]; then

CONTRIBUTING.md

@@ -64,7 +64,7 @@ Se o Pull Request for a primeira vez que você olha o código, o método falhou.
 **O PR será REPROVADO se:**
 
 1. Não atualizar nenhum arquivo em `docs/` ou `specs/`.
-2. A descrição não contiver a seção _"O que este PR faz e por quê"_ preenchida por você com pelo menos 200 caracteres (Não cole o _diff_ nem a saída da IA; explique com suas palavras).
+2. A descrição não contiver a seção _"O que este PR faz e por quê"_ preenchida por você com pelo menos 400 caracteres (Não cole o _diff_ nem a saída da IA; explique com suas palavras).
 
 **Exceção (Manutenção puramente técnica):**
 Se a mudança não afeta o produto (ex: atualizar versão, refatorar código, arrumar formatação), você não precisa criar um `spec.md`. Abra o PR direto e aplique a etiqueta `manutencao`.

apps/api/README.md

@@ -0,0 +1 @@
+Reservada para uma API própria, se um dia existir — o `/utf-setup` não gera nada aqui (ver `docs/architecture.md` §3).

docs/architecture.md

@@ -24,7 +24,7 @@
 | Fonte | Onde configurar | Serve para |
 | :---- | :-------------- | :--------- |
 | Constituição da IA | `.agents/rules/utf-rules.md` (via `CLAUDE.md`) | Regras inegociáveis: fases do SDD, 2 rodadas, revisores distintos, Gitflow |
-| Fluxos da IA | `.agents/workflows/` | PRD, flows, architecture, setup, ciclo por Issue, ciclo por tarefa, tutor |
+| Fluxos da IA | `.agents/workflows/` | PRD, backlog, design, architecture, setup, ciclo por Issue, ciclo por tarefa, tutor |
 | Agentes (subagentes) | `.agents/agents/` (cascas em `.claude/`, `.cursor/`, `.opencode/`) | Implementador, revisores, auditor final e tutor |
 | Ficha da disciplina | `docs/checklist.md` | Regras do projeto, IDs e entregas |
 | Protótipo (Stitch/Figma) | [link público] | Telas, jornadas e hierarquia visual (ID1) |

docs/design-tokens.md

@@ -49,6 +49,30 @@ Uma progressão só, usada em tudo.
 | desabilitado | |
 | carregando | |
 
+## Breakpoints (Mobile-First)
+
+O design nasce para a menor tela e cresce (ID2). Toda tela do protótipo tem
+versão mobile antes da versão desktop.
+
+| Token | Largura mínima | Vale para |
+| --- | --- | --- |
+| `sm` | | |
+| `md` | | |
+| `lg` | | |
+
+## Identidade PWA
+
+Os valores abaixo alimentam o `manifest.webmanifest` no `/utf-setup` (ID3).
+
+| Campo | Valor |
+| --- | --- |
+| Nome curto (`short_name`) | |
+| Cor de tema (`theme_color`) | |
+| Cor de fundo (`background_color`) | |
+| Ícone | |
+| Modo de exibição (`display`) | `standalone` |
+| Comportamento visual offline | [o que a pessoa vê sem rede] |
+
 ## Protótipo
 
 **Link:** [Figma / Stitch / equivalente]