Revisão de conformidade: modo review do verify.sh e skill revisao-conformidade

.claude/agents/revisor-conformidade.md

@@ -1,6 +1,6 @@
 ---
 name: revisor-conformidade
-description: Confere, em contexto novo, se uma mudança entrega o que foi planejado para o ticket - critérios de aceite, testes contra os cenários, contrato e schema contra o commit de plano e documentos donos. Recebe o caminho de um arquivo de diff, o identificador do ticket (ou, sem ticket, os critérios) e os caminhos da mensagem do commit de plano e da visão do desvio do contrato. Devolve achados, e não corrige nada. Use depois da /code-review e antes do full, como descrito no AGENTS.md da raiz.
+description: Confere, em contexto novo, se uma mudança entrega o que foi planejado para o ticket - critérios de aceite, testes contra os cenários, contrato e schema contra o commit de plano e documentos donos. Recebe o caminho de um arquivo de diff, o identificador do ticket (ou, sem ticket, o caminho do arquivo de critérios) e os caminhos da mensagem do commit de plano e da visão do desvio do contrato. Devolve achados, e não corrige nada. Use depois da /code-review e antes do full, pela skill revisao-conformidade.
 tools: Read, Grep, Glob, mcp__linear-server__get_issue
 ---
 
@@ -11,7 +11,7 @@ Você confere a conformidade de uma mudança que outro agente escreveu com o que
 ## O que você recebe
 
 - **O caminho de um arquivo de diff,** com a mudança inteira, inclusive o que ainda não está em commit. Leia-o por completo. Depois leia os arquivos alterados inteiros, e não só o trecho do diff, e os arquivos que os chamam.
-- **O identificador do ticket.** Leia o ticket e a spec pai dele no Linear. Em mudança sem ticket, os critérios vêm no pedido.
+- **O identificador do ticket.** Leia o ticket e a spec pai dele no Linear. Em mudança sem ticket, vem no lugar dele o caminho do arquivo de critérios (`docs/tickets/sem-ticket/<nome>/criterios.md`): leia-o por completo, e confira a mudança contra ele.
 - **O caminho da mensagem do commit de plano** (`docs/tickets/<issue>/<ticket>/plano.txt`), ou o aviso de que ela não existe. São as decisões aprovadas, os arquivos e interfaces e a mudança de dados: uma decisão da mensagem que o diff contraria, sem que o documento dono e o ticket tenham mudado junto, é achado.
 - **O caminho da visão do desvio do contrato** (`docs/tickets/<issue>/<ticket>/contract-drift.txt`), ou o aviso de que ela não existe. Ela mostra o que mudou no contrato e no schema desde o commit de plano, que foi o desenho aprovado.
 

.claude/skills/implement-spec/SKILL.md

@@ -33,8 +33,8 @@ Communication to and from subagents should be sparse. Communicate primarily thro
 
 6. If this changes the **frontier** of available tickets, kick off more **implementer subagents** to work on the new tickets. This allows for maximum concurrency.
 
-7. Once all tickets are complete, call the Skill tool with `simplify` and then with `code-review` on the integration branch. Then run the conformance review once per ticket, as the root `AGENTS.md`, section "Revisão de conformidade", describes: the same diff of the integration branch, with each ticket's identifier, plan message and contract drift. Fix all issues raised by the code review and the conformance review in a single **implementer subagent**. Then, in the main session, run `scripts/verify.sh full` once, before the commit that closes the work, as the root `AGENTS.md`, section "Definição de pronto", describes.
+7. Once all tickets are complete, call the Skill tool with `simplify` and then with `code-review` on the integration branch. Then call the Skill tool with `revisao-conformidade` once per ticket: each review gets the same diff of the integration branch, in that ticket's folder, with its identifier, plan message and contract drift. Triage each ticket's findings in the main session, as step 5 of that skill says, and fix the issues raised by the code review and the findings you accepted in a single **implementer subagent**. Then, in the main session, run `scripts/verify.sh full` once, before the commit that closes the work, as the root `AGENTS.md`, section "Definição de pronto", describes.
 
-8. If a draft PR exists, mark it ready for review. Otherwise, resolve each ticket the way the issue tracker closes work, and report the integration branch.
+8. If a draft PR exists, publish each ticket's review comment, as the `revisao-conformidade` skill describes in "Publish", and mark the PR ready for review. Otherwise, resolve each ticket the way the issue tracker closes work, and report the integration branch.
 
 9. Clean up all **implementer subagent** worktrees.

.claude/skills/implement/SKILL.md

@@ -14,6 +14,6 @@ Call the Skill tool with "tdd" where possible, at pre-agreed seams.
 
 While working, run only the tests tied to the files you changed, with the commands in the project's `AGENTS.md`; the stop hook already runs the type and lint checks.
 
-Once done, call the Skill tool with "simplify" and then with "code-review" to review the work, then run the conformance review, as the root `AGENTS.md`, section "Revisão de conformidade", describes, and fix the findings you agree with. Then run the full verification once, before the commit that closes the work, as the root `AGENTS.md`, section "Definição de pronto", describes.
+Once done, call the Skill tool with "simplify" and then with "code-review" to review the work, then call the Skill tool with "revisao-conformidade" to run the conformance review and triage its findings, as that skill describes. Then run the full verification once, before the commit that closes the work, as the root `AGENTS.md`, section "Definição de pronto", describes.
 
 Commit your work to the current branch.

.claude/skills/revisao-conformidade/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: revisao-conformidade
+description: "Run the conformance review of a change that alters code in apps/: prepare its inputs with scripts/verify.sh review, call the revisor-conformidade subagent with paths only, record and triage the findings, then publish them as a PR comment. Use after /code-review and before scripts/verify.sh full, and again when the pull request is opened."
+---
+
+How to run the conformance review that the root `AGENTS.md` requires, and what to do with its result. The rule (who reviews, when, and that the review does not block) is in that file, section "Revisão de conformidade"; what the `revisor-conformidade` subagent checks is in the root `REVIEW.md` and in `.claude/agents/revisor-conformidade.md`.
+
+The skill has two parts, at two moments: **Review**, after `/code-review` and before the `full`, so the fixes go into the single full verification; and **Publish**, when the pull request exists, which may be in another session.
+
+## Review
+
+1. **Folder.** With a ticket, the review lives in the ticket's folder, `docs/tickets/<pai>/<ticket>/`, next to its acceptance file. Without a ticket, it lives in `docs/tickets/sem-ticket/<nome>/`, with a short lowercase name you choose (letters, digits and hyphens). Without a ticket, first write the acceptance criteria of the change in `criterios.md` in that folder, one numbered criterion per line, from what was asked and not from what was done. The script refuses to run without it.
+
+2. **Inputs.** From the repository root, run:
+
+   ```bash
+   scripts/verify.sh review <pai> <ticket>     # with a ticket
+   scripts/verify.sh review sem-ticket <nome>  # without one
+   ```
+
+   It writes, in the folder, `review.diff` (everything the branch changed since it left the base, up to the working tree, with every new file Git does not ignore) and, with a ticket, `plano.txt` (the plan commit message) and `contract-drift.txt` (the contract and schema drift since the plan commit, always written). It fails, and says what to do, when the ticket has no plan commit, when `criterios.md` is missing, when the inputs would not be ignored by Git, or, with a ticket, when the `api` container is down. The base is `origin/main`; for a pull request to another base, set `HARNESS_BASE_REF`, as in `HARNESS_BASE_REF=test/main`. Read the list of files the diff adds, committed or not: a file the change created that is not there is ignored by Git, and stays out of the review.
+
+3. **Call the subagent.** Call `revisor-conformidade` with only the input lines the script printed: the path of the diff, the ticket identifier and the paths of the plan message and the contract drift, or, without a ticket, the path of `criterios.md` and the notice that there is no plan commit. Do not add your summary of the change, your opinion of it or what you think deserves attention: the value of the review is that it does not start from your conclusions. Run it in the branch checkout, because it reads the branch's acceptance file.
+
+4. **Record.** As soon as the subagent returns, write `revisao.md` in the same folder, in the format below, with its report verbatim inside `<details>` and one table row per finding. Do not omit a finding nor edit the report. With no findings, write the file anyway, with the table empty and the report. Git ignores the file, as it ignores everything in the ticket folder but the acceptance file.
+
+5. **Triage.** Decide each finding and fill its row:
+   - **Agree:** fix it. The situation is `Corrigido`, and the reason says what changed.
+   - **Disagree:** the situation is `Não corrigido`, and the reason says why it stays as it is.
+   - **High severity you would leave unfixed:** stop and ask the user before going on. Write the decision and that it was the user's in the reason.
+
+   In `/implement-spec`, one implementer subagent fixes the findings of `/code-review` and of every ticket's review, as that skill says. The commit after the fixes does not go through the reviewer again: the `full` verifies it.
+
+6. **Go on** to the `full`, as the root `AGENTS.md` says in "Definição de pronto". In `/implement-spec`, that is after every ticket's review and the fixes, and not after each ticket.
+
+## Publish
+
+When the pull request exists, post each `revisao.md` of the branch as one comment, one per ticket. The file is local and ignored by Git, so publish from the checkout where the review ran; if it is missing (another checkout, a cleaned worktree), run the review again instead of writing the comment from memory.
+
+```bash
+gh pr comment <pr> --body-file docs/tickets/<pai>/<ticket>/revisao.md
+```
+
+Add `--repo <owner>/<repo>` when the pull request is not on the default remote. If the pull request already has the comment of that ticket, edit it instead of posting a second one: find its id by the title, then replace its body.
+
+```bash
+gh api repos/<owner>/<repo>/issues/<pr>/comments --paginate \
+  --jq '.[] | select(.body | startswith("## Revisão de conformidade: <ticket>\n")) | .id'
+gh api -X PATCH repos/<owner>/<repo>/issues/comments/<id> -F body=@docs/tickets/<pai>/<ticket>/revisao.md
+```
+
+The comment is the record the root `AGENTS.md` asks for, section "Revisão de conformidade".
+
+## Format of `revisao.md`
+
+The title names the ticket, or `sem ticket (<nome>)` for a change without one.
+
+```markdown
+## Revisão de conformidade: <ticket>
+
+| # | Severidade | Achado | Situação | Motivo |
+| --- | --- | --- | --- | --- |
+| 1 | alta | O que o revisor apontou | Corrigido | O que mudou |
+| 2 | média | O que o revisor apontou | Não corrigido | Por que ficou como está |
+
+<details>
+<summary>Relatório do revisor, na íntegra</summary>
+
+(o relatório, sem edição)
+
+</details>
+```
+
+## Without subagents
+
+In an agent that cannot call a subagent, run the review in a new session, with the instructions of `.claude/agents/revisor-conformidade.md` and the same inputs, and record and publish it the same way.

.claude/skills/revisao-conformidade/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Revisão de conformidade"
+  short_description: "Review a change against its plan and publish the findings"
+policy:
+  allow_implicit_invocation: true

AGENTS.md

@@ -167,46 +167,9 @@ O aceite é conferido na máquina antes do push, como descrito em "Antes do push
 
 **Revisão de conformidade**
 
-Quem escreveu o código não é quem o confere. Toda mudança que altera código em `apps/` passa pelo subagente `revisor-conformidade`, que não viu a implementação e confere se ela entrega o que foi planejado: o aceite, os testes contra os cenários, o contrato e o schema contra o commit de plano e os documentos donos. O que ele confere está no `REVIEW.md` da raiz, que o Copilot e o Claude Code Review também leem no PR, e o que só ele confere, em `.claude/agents/revisor-conformidade.md`. Os defeitos gerais de código ficam com a `/code-review`, e uma revisão feita na mesma sessão que escreveu o código não substitui esta.
+Quem escreveu o código não é quem o confere. Toda mudança que altera código em `apps/` passa pelo subagente `revisor-conformidade`, que não viu a implementação e confere se ela entrega o que foi planejado: o aceite, os testes contra os cenários, o contrato e o schema contra o commit de plano e os documentos donos. O que ele confere está no `REVIEW.md` da raiz, que o Copilot e o Claude Code Review também leem no PR. Os defeitos gerais de código ficam com a `/code-review`, e uma revisão feita na mesma sessão que escreveu o código não substitui esta.
 
-No fluxo do ticket, ela vem depois da `/code-review` e antes do `full`, para as correções entrarem na única verificação completa: implementação, `/simplify`, `/code-review`, revisão de conformidade, correções, `full` e commit.
-
-1. **Gere o diff, a mensagem do plano e a visão do desvio na pasta do ticket,** `docs/tickets/<issue>/<ticket>/`, a mesma do arquivo de aceite que o commit de plano criou; numa mudança sem ticket, `docs/tickets/sem-ticket/<nome>/`. O diff é o da pasta de trabalho contra a base, com os arquivos novos, porque a revisão vem antes do commit:
-
-   ```bash
-   git add -N -- <arquivos novos da mudança>
-   git diff origin/main > docs/tickets/<issue>/<ticket>/review.diff
-   plano="$(git log --follow --diff-filter=A --format=%h -1 -- docs/tickets/<issue>/<ticket>/aceite.md)"
-   git show -s --format=%B "$plano" > docs/tickets/<issue>/<ticket>/plano.txt
-   scripts/verify.sh contract "$plano" > docs/tickets/<issue>/<ticket>/contract-drift.txt
-   ```
-
-   O `git add -N` só registra que os arquivos novos existem, para o diff trazê-los, sem prepará-los para o commit. Confira com o `git status --short` que nenhum arquivo da mudança ficou de fora: o que não está no diff fica fora da revisão, sem aviso. Sem commit de plano, não há mensagem nem visão do desvio. Os arquivos não aparecem no `git status`, porque o Git os ignora: ele versiona só o arquivo de aceite da pasta do ticket.
-
-2. **Chame o subagente `revisor-conformidade`** passando só o caminho do diff, o identificador do ticket e os caminhos da mensagem do plano e da visão do desvio, ou o aviso de que elas não existem. Numa mudança sem ticket, passe os critérios de aceite. Não passe o seu resumo da mudança, a sua opinião sobre ela nem o que você acha que merece atenção: o valor da revisão está em ela não partir das suas conclusões. Rode a revisão no checkout da branch, porque ele lê o arquivo de aceite dela.
-3. **Corrija os achados com que você concorda** e siga para o `full` (ver "Definição de pronto").
-4. **Publique o resultado como comentário no PR,** quando ele for aberto, com o título `## Revisão de conformidade`, neste formato:
-
-   ```markdown
-   ## Revisão de conformidade
-
-   | # | Severidade | Achado | Situação | Motivo |
-   | --- | --- | --- | --- | --- |
-   | 1 | alta | O que o revisor apontou | Corrigido | O que mudou, e em que commit |
-   | 2 | média | O que o revisor apontou | Não corrigido | Por que ficou como está |
-
-   <details>
-   <summary>Relatório do revisor, na íntegra</summary>
-
-   (o relatório, sem edição)
-
-   </details>
-   ```
-
-- **Todo achado entra na tabela,** inclusive o que você considera errado. Nesse caso, a situação é "Não corrigido" e o motivo diz por quê. Não omita achado nem edite o relatório.
-- **A revisão não bloqueia.** O que fazer com um achado não corrigido é decisão do usuário no merge. A CI não lê esse comentário.
-- **Sem achados também é resultado:** publique o comentário mesmo assim, com o relatório.
-- **Em agente sem subagentes,** faça a revisão numa sessão nova, com as instruções de `.claude/agents/revisor-conformidade.md`, e publique o comentário do mesmo jeito.
+No fluxo do ticket, ela vem depois da `/code-review` e antes do `full`, para as correções entrarem na única verificação completa: implementação, `/simplify`, `/code-review`, revisão de conformidade, correções, `full` e commit. A revisão não bloqueia: todo achado, corrigido ou não, vai para um comentário no PR, e a decisão sobre o que ficou sem corrigir é do usuário no merge. Como preparar a revisão, chamar o subagente, tratar os achados e publicar o comentário está na skill `revisao-conformidade`.
 
 Os comandos de teste, de lint e de formatação de cada projeto estão no `AGENTS.md` dele.
 

REVIEW.md

@@ -4,7 +4,7 @@ O que toda revisão deste repositório confere além dos defeitos de código: se
 
 ## Onde está o padrão
 
-- **O aceite:** o arquivo citado na seção `## Aceite` do corpo do PR, `docs/tickets/<issue>/<ticket>/aceite.md`. Cada critério é um título `## <ticket>-CA<n>`, com a marca, o cenário (Dado, Quando, Então) e, nos de teste, o teste previsto. O formato é o da skill de plano, `.claude/skills/plan-ticket/formatos/aceite.md`. Com `nenhum`, não há arquivo de aceite: os critérios, quando há, vêm no pedido de revisão; confira o motivo dado.
+- **O aceite:** o arquivo citado na seção `## Aceite` do corpo do PR, `docs/tickets/<issue>/<ticket>/aceite.md`. Cada critério é um título `## <ticket>-CA<n>`, com a marca, o cenário (Dado, Quando, Então) e, nos de teste, o teste previsto. O formato é o da skill de plano, `.claude/skills/plan-ticket/formatos/aceite.md`. Com `nenhum`, não há arquivo de aceite: na máquina, os critérios vêm no arquivo que o pedido de revisão aponta; confira o motivo dado.
 - **O plano:** o commit da branch que criou esse arquivo. A mensagem dele traz as decisões, os arquivos e interfaces e a mudança de dados; na máquina, ela chega ao revisor como arquivo.
 - **O contrato e o schema:** `apps/api/openapi.json` e `apps/api/prisma/schema.prisma`. O formato de cada rota está no `docs/lld.md`, seção 3, "Formato de uma rota no snapshot", e o de cada tabela, na seção 2, "Formato de uma tabela no schema".