@evertonferreira96/agents 0.0.0-stage → 0.1.0

package/.claude/skills/arch-api/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: arch-api
+description: Implementa, revisa e refatora APIs NestJS contract-first - contrato OpenAPI por caso de uso em `props.surface` e controller fino em `exec.surface`, schemas Zod nomeados em `entities`, um service por caso de uso com `execute`, regras puras, autorização por recurso no arquivo de access do domínio, mapper e erros com `code` estável, port e adapter por domínio, módulos `surface` e `sgbds` por domínio, capacidades técnicas em `common`, em geral atrás de port e adapter, `openapi.json` gerado que alimenta os clients, paginação, idempotência, segurança, observabilidade e testes. Use ao criar ou revisar endpoints, surfaces, services, módulos, ports, adapters, repositórios, guards, decorators, env, erros ou o `openapi.json` de qualquer API NestJS. Para schema, SQL, índices e migrations no nível do banco, carregue `arch-db`. Não use para o web Next.js (`arch-web`) nem para o app React Native (`arch-app`).
+---
+
+# Arquitetura de API NestJS contract-first
+
+```text
+Fonte única: o props.surface declara path, verbo, status, security e schemas; o resto consome ou copia.
+O exec.surface é fino: guards, pipes Zd* e um service.execute.
+Um caso de uso por arquivo: <Acao>Service.execute decide; rules são puras; access autoriza o recurso.
+O port abstrai com tipos escritos à mão; o adapter executa, abre a transação e traduz o erro do banco.
+Capacidade técnica mora em common/<capacidade>, em geral atrás de um port; o banco, no módulo global de banco.
+O openapi.json gerado é o contrato dos clients; geração, typecheck e testes quebram quando algo diverge.
+```
+
+A skill descreve o padrão com nomes genéricos (`invoices`, `customers`, `<domain>`, `<acao>`). Nomes de pasta, scripts, decorators e helpers vêm do repo: faça o inventário antes. Onde o repo divergir, siga o repo e proponha migração em ondas (`references/review.md` §3). ADRs do repo vencem a skill.
+
+| Abra quando for | Reference |
+|---|---|
+| escrever ou revisar `props`/`exec`, decorators de contexto, erros no contrato, paginação, nomes de schema, registry, versionamento, paridade | [`references/contract.md`](references/contract.md) |
+| escrever service, rules, access, mapper, errors, port, adapter, SQL do adapter, módulos `sgbds`/`surface`, worker, outbox, idempotência | [`references/domain.md`](references/domain.md) |
+| criar ou usar uma capacidade em `common/` (mailer, storage, hash, env, docs, observability, utils, bootstrap) | [`references/common.md`](references/common.md) |
+| mexer em auth, guards, rate limit, tenant, formato de erro, logs, resiliência ou revisar OWASP | [`references/security.md`](references/security.md) |
+| escolher o formato de um endpoint ou conferir o checklist dele | [`references/endpoints.md`](references/endpoints.md) |
+| escrever testes, abrir domínio novo, planejar migração, ADR, scorecard de PR | [`references/review.md`](references/review.md) |
+| tocar schema, SQL, índice, migration, seed, lock ou pool | skill `arch-db` (vence esta no nível do banco) |
+
+---
+
+## Antes de editar
+
+Inventário (o que o repo já tem vence o que esta skill sugere):
+
+```txt
+<pm> e monorepo (<pm> --filter <app> <script>); versões do Nest e do Zod; aliases (@/)
+ORM e driver; nome e exports do módulo global de banco (na referência: common/sgbds)
+padrão de surfaces (props/exec planos em surfaces/) e scaffold de domínio (scripts/*.mjs), se houver
+decorators Zd*, AuthUser e de contexto; guards de auth e de rate limit
+exceções de domínio (common/http/errors), formato de erro e envelope (common/schemas)
+registry OpenAPI, script de geração, onde ficam o openapi.json e o client gerado
+policy service de permissões que os arquivos <domain>-access chamam
+ferramenta de migration e runner de seed; runner de teste, configs e <domain>.fixtures-spec.ts
+scripts reais do package.json (o README pode estar desatualizado; o package.json vence)
+```
+
+1. **Leia o vizinho.** Abra um domínio maduro (com `doc.md`, `*-access.ts` e specs) e copie a forma dele. Critério: o arquivo novo tem os mesmos imports, sufixos e ordem de blocos do vizinho.
+2. **O helper já existe?** Paginação, erros, decorators, exceções, utils e capacidades de `common/` vêm antes de criar. Critério: nenhum helper novo duplica um de `common/`.
+3. **De onde vem o `.openapi()`?** O repo estende o `z` uma vez num módulo de setup carregado no boot (na referência, o `main.ts` importa `common/schemas/setup`, e os props importam `z` de `'zod'`). Todo ponto de entrada que carrega props sem passar pelo `main.ts` (script de geração, setup do runner de teste) precisa importar esse módulo antes, senão quebra com `.openapi is not a function`. Critério: o import do `z` segue o do vizinho e o `openapi:generate` roda.
+4. **Vai tocar tabela, SQL, índice ou migration?** Carregue `arch-db` antes de escrever. Critério: a migration segue a ferramenta e o formato das vizinhas.
+5. **Terminou?** Rode geração do OpenAPI, typecheck, lint e testes. Critério: os quatro passam e o diff do `openapi.json` contém só as operações que você mudou.
+
+Se algo não existir, proponha criação incremental e localizada; não invente dependência global.
+
+---
+
+## Mapa
+
+```txt
+src/
+  common/
+    server/                 app.module.ts  main.ts
+    <capacidade>/           com port e adapter: hash, mailer, encrypters, storage, messaging, resilience, secrets, html
+                              ports/<capacidade>.<papel>.port.ts  adapters/<tecnologia>.<capacidade>.<papel>.adapter.ts  <capacidade>.module.ts
+                            service concreto: cache, queue
+                            forma própria: auth, environments (port + provider), realtime (port + gateway)
+    decorators/  guards/  policies/      HTTP transversal: contexto, autenticação, ownership
+    docs/openapi/           registries.docs.ts  response.docs.ts  build.ts  generate.ts
+    http/                   enums/  errors/
+    observability/          interceptor de correlação, filter de exceções, logger estruturado
+    prototypes/             extensões globais importadas no boot
+    schemas/                paginations.ts  errors.ts  setup.ts  (só cross-domain)
+    sgbds/                  containers/  ports/  adapters/<orm>/  settings/  migrations/  seeds/  generated/   (conteúdo: arch-db)
+    surfaces/               surface.module.ts   (agrega todos os <domain>.surface.module.ts)
+    utils/<tipo>/           <nome>.<tipo>.util.ts (maioria; siga o vizinho da pasta), teste *.unit.spec.ts
+  modules/<domain>/
+    <domain>.surface.module.ts        controllers (exec) + providers (services); importa <Domain>SgbdsModule e os de quem depende
+    <domain>.sgbds.module.ts          { provide: <Domain>RepositoryPort, useClass: <Tecnologia><Domain>RepositoryAdapter }; exporta o port
+    doc.md                            visão, tabela endpoint x rota x permissão, autorização, regras, escrita, persistência, pendências
+    entities/<domain>.entities.ts     schemas Zod nomeados (.openapi('Name')) e tipos do domínio
+    ports/<domain>.repository.port.ts classe abstrata + tipos Row/Record/New/Write escritos à mão
+    adapters/<tecnologia>.<domain>.repository.adapter.ts (+ .spec.ts)
+    adapters/<domain>.sql.ts          SQL cru montado por funções puras (leituras quentes)
+    adapters/<domain>-db-errors.ts    constraint/trigger -> exceção de domínio com code
+    services/<acao>.service.ts (+ .spec.ts)    um caso de uso por arquivo: <Acao>Service.execute(input)
+    services/<assunto>.rules.ts (+ .spec.ts)   regra pura
+    services/<domain>-access.ts (+ .spec.ts)   autorização por recurso (a policy do domínio)
+    services/<domain>.mapper.ts                Row -> resposta do contrato (datas ISO)
+    services/<domain>-errors.ts                fábricas de exceção com code (na referência, nome no singular do recurso)
+    services/*.resolver.ts | *-context.ts | *.helpers.ts | <domain>.fixtures-spec.ts
+    surfaces/<acao>.<domain>.props.surface.ts  contrato OpenAPI: registerPath + instructions + Instruction
+    surfaces/<acao>.<domain>.exec.surface.ts   controller fino: guards, Zd*, service.execute
+    <assunto>.worker.ts                        consumidor de fila do domínio (quando há)
+test/e2e/*.e2e.spec.ts    libraries/test/ (configs do runner)    openapi.json    generated/openapi-client.d.ts
+```
+
+O nome `sgbds` é do repo de referência; se o seu chama o módulo de banco de `database`, `db` ou `prisma`, troque o nome e mantenha os papéis. Pastas que o repo não usa (`dtos/`, `policies/` e `mappers/` dentro do módulo) não nascem por causa desta skill.
+
+Colocação:
+
+- Schema de domínio nasce em `entities/` do módulo dono; `common/schemas` guarda só o que dois ou mais domínios usam (paginação, erros, entidades compartilhadas).
+- Um domínio usa outro importando, no seu `surface.module`, o módulo que exporta o port ou o service (`<Other>SgbdsModule`); o import TypeScript da classe é só o token de DI.
+- Capacidade técnica nova é uma pasta `common/<capacidade>/` com port, adapter e módulo (receita em `references/common.md` §2).
+- Regra repetida por vários services do domínio vira `*.rules.ts` (pura); leitura repetida (carregar e serializar o detalhe, conferir referências) vira função em `<domain>-context.ts`; resolução do recurso pai com 404 vira `<x>.resolver.ts` injetável.
+- Ownership transversal (dono do recurso = ator) mora em `common/policies`; autorização por recurso do domínio mora em `<domain>-access.ts`.
+
+---
+
+## Camadas
+
+| Peça | Responsabilidade | Depende de |
+|---|---|---|
+| `props.surface` | contrato: constantes, schemas registrados, `registerPath`, `instructions`, `Instruction` | `z`, `entities`, `common/docs`, `common/schemas`, `common/http/enums` |
+| `exec.surface` | rota, guards, status, pipes, um `execute` | o props, o service, `common/decorators`, `common/guards`, `common/http/enums` |
+| `<acao>.service` | o caso de uso: resolve, autoriza, decide, grava, devolve o contrato | port, rules, access, mapper, errors, entities, `common/http/errors`; o que outros módulos exportam |
+| `*.rules` | regra pura com teste | entities, `common/http/errors` |
+| `<domain>-access` | permissão, tenant, ownership, estado e visibilidade do recurso | policy service de permissões, `common/auth`, `common/http/errors`, tipos do port |
+| `<domain>.mapper` | `*Row` -> schema de resposta | tipos de entities e do port, access (`can`), rules |
+| `<domain>-errors` | fábricas de exceção com `code` | `common/http/errors` |
+| `entities` | schemas Zod nomeados reutilizados por props, service e mapper | `z` |
+| port | assinaturas e tipos escritos à mão | `import type` (regra 10) |
+| adapter (+ `.sql`, `-db-errors`) | leitura, escrita, transação, tradução de constraint | port, módulo global de banco, errors e rules do domínio, `common/utils` |
+| `<domain>.sgbds.module` | liga port -> adapter e exporta o port | port, adapter |
+| `<domain>.surface.module` | controllers, providers, módulos importados, registro dos props | exec, services, `SgbdsModule`s, props por efeito colateral |
+| `doc.md` | documentação viva do domínio | - |
+| `common/<capacidade>` | capacidade técnica, em geral atrás de port (forma de cada uma no Mapa) | SDK da tecnologia, env provider |
+| `common/sgbds` (módulo global de banco) | exporta os clientes de banco, traduz erro genérico, guarda migrations e seeds | ORM e driver |
+
+---
+
+## Nomes
+
+| Arquivo | Exporta |
+|---|---|
+| `surfaces/<acao>.<domain>.props.surface.ts` | `instructions` e `namespace Instruction` (`Params`, `Query`, `Request`, `Response`) |
+| `surfaces/<acao>.<domain>.exec.surface.ts` | `<Acao>Surface` com método `exec` |
+| `services/<acao>.service.ts` | `<Acao>Service` com `execute(input)`; `<acao>` em kebab do `operationId` |
+| `services/<assunto>.rules.ts` | funções puras e constantes |
+| `services/<domain>-access.ts` | `<DOMAIN>_ACTIONS`, `assertCan*`, `can`, `viewerOf` |
+| `services/<domain>.mapper.ts` | `serialize<Coisa>(row)` |
+| `services/<domain>-errors.ts` (na referência, nome no singular do recurso) | fábricas como `stale<Coisa>()` |
+| `entities/<domain>.entities.ts` | `<coisa>Schema` e `type <Coisa> = z.infer<...>` |
+| `ports/<domain>.repository.port.ts` | `<Domain>RepositoryPort` e tipos `<Coisa>Row`, `<Coisa>Record`, `New<Coisa>`, `<Coisa>Write` |
+| `adapters/<tecnologia>.<domain>.repository.adapter.ts` | `<Tecnologia><Domain>RepositoryAdapter` |
+| `adapters/<domain>.sql.ts` | `build<Coisa>Query(...)` -> `{ text, values }`, constantes `*_SQL`, mapa `*_SORT` |
+| `adapters/<domain>-db-errors.ts` | `rethrow<Domain>DbError` |
+| `ports/<x>.provider.port.ts` / `adapters/<tecnologia>.<x>.provider.adapter.ts` | `I<X>Provider` / `<Tecnologia><X>ProviderAdapter` (integração externa do domínio) |
+| `<domain>.sgbds.module.ts` / `<domain>.surface.module.ts` | `<Domain>SgbdsModule` / `<Domain>SurfaceModule` |
+| `<assunto>.worker.ts` | consumidor de fila do domínio |
+| `common/utils/<tipo>/<nome>.<tipo>.util.ts` (maioria; siga o vizinho da pasta), teste `*.unit.spec.ts` | helper puro, reexportado pelo `index.ts` da pasta |
+| specs | `*.spec.ts` ao lado do arquivo; `*.unit.spec.ts` em utils; `<domain>.fixtures-spec.ts`; `test/e2e/*.e2e.spec.ts` |
+
+---
+
+## O caminho de uma request
+
+```txt
+guards        AuthUserGuard (se o props declara security); guard de rate limit do repo em rota sensível
+interceptor   correlação: traceId do header ou novo; envolve pipes + handler e loga o desfecho
+pipes         ZdParam / ZdQuery / ZdBody com instructions.settings.request.*
+exec.surface  this.service.execute({ actorId: user.id, ...params, ...query, ...body })
+  service     resolve o recurso -> assert* do <domain>-access -> rules -> port
+    adapter   leitura: driver + <domain>.sql.ts | escrita: ORM em transação; <domain>-db-errors traduz
+  mapper      *Row -> resposta do contrato (datas ISO), devolvida pelo service
+erro          a exceção de domínio carrega o corpo (shape de common/schemas/errors.ts); a causa técnica vai só para o log
+```
+
+---
+
+## Regras não negociáveis
+
+1. **Fonte única.** `Method`, `Endpoint`, `OperationId`, `Tags`, `security`, status e schemas vivem no `props.surface`. O `exec` usa `@Controller()` e repete no decorator do verbo o `Endpoint` literal sem a barra inicial (é o que o scaffold gera); ao renomear rota, mude os dois no mesmo commit. A checagem de paridade rota x documento do repo confere, se existir; senão, o e2e da rota é a trava. Pipes e tipos vêm de `instructions` e `Instruction.*`, nunca escritos à mão.
+2. **`exec` fino.** Guards, `@HttpCode(http.status.*)`, `Zd*` com o schema do contrato e uma chamada a `execute`. Nada de regra, SQL, token, hash, transação, try/catch ou chamada externa.
+3. **Service recebe contexto extraído** (`actorId`, ref de tenant, IP, `traceId`), nunca `Request`, headers ou objeto do Nest. O `type Input` do service é escrito à mão e espelha o que o `exec` espalha.
+4. **`.strict()` em todo params, query e body.** É o que torna seguro o spread no `exec`: campo extra vira 400 antes do service. O adapter grava campo a campo a partir de `New<Coisa>`/`<Coisa>Write`; nenhum método recebe o body cru.
+5. **Schema que vira tipo no client tem nome**: `.openapi('<Nome>')` mais `openapi.register('<Nome>', schema)` no props; schemas de domínio nomeados em `entities/`.
+6. **Datas no JSON são string ISO** (`z.string().datetime()`); `Date` vira ISO no mapper.
+7. **Erros declarados onde ocorrem.** `...docs.response` (400/401/403/404) em todo endpoint; `...docs.conflict` e `...docs.unprocessable` só quando o endpoint devolve 409/422. Todo 409/422 tem `code` estável listado na `description` do `registerPath`. Módulos novos usam `<domain>.<motivo>`; módulo legado mantém o formato que já publica, porque mudar `code` é breaking.
+8. **Guard runtime = `security` do contrato**, nas duas direções, sem guard global de autenticação. Rota protegida: `@UseGuards(AuthUserGuard)` e `security: [{ bearerAuth: [] }]`. Rota pública: sem guard e `security: []` no `registerPath`; siga o vizinho público: se ele só omite `security`, o documento herda o global e mostra a rota como protegida, e isso se registra como melhoria (`references/review.md` §3).
+9. **`<domain>-access` autoriza o recurso.** Permissão, tenant, ownership e estado são decididos ali, chamados pelo service antes de qualquer escrita; quando revelar a existência é risco, responda 404 em vez de 403.
+10. **Port com tipos escritos à mão.** Do ORM e do módulo de banco entram só `import type` de enums gerados e do tipo de paginação; nunca model, payload, select ou namespace do ORM. Ausência é `null`.
+11. **Cliente de banco só do módulo global de banco.** O adapter injeta os serviços que ele exporta (na referência, ORM para escrita e driver para leitura quente); nenhum módulo abre conexão nem cria pool. Pool e timeouts: `arch-db`.
+12. **SQL só parametrizado** (`$n` montado por função pura em `<domain>.sql.ts`); `ORDER BY` só por mapa literal atrás de `z.enum` no contrato, sempre com tiebreaker por id.
+13. **Lista tem teto e `meta` pelo helper único**: `paginationQuery`, `paginatedResponse(item)` e `toPaginationMeta`. Envelope `{ data }` ou `{ data, meta }`, nenhum outro.
+14. **Transação dentro do método do adapter**, sem HTTP, e-mail, fila ou upload dentro. A constraint decide a corrida e o `<domain>-db-errors` a traduz para exceção com `code`; `version` no `WHERE` que não casa vira 409 `<domain>.stale`.
+15. **Fail-closed.** Toda env no schema Zod validado no boot; exposição (docs, CORS, `trust proxy`, limite de body) fechada por padrão, com o detalhe de cada uma em `references/security.md` §1.
+16. **Migration pela ferramenta do repo**, revisada com `arch-db`; nunca no boot nem por `push`/`synchronize`.
+17. **`doc.md` do domínio muda no mesmo PR** que muda endpoint, permissão, regra ou persistência.
+
+---
+
+## Criando um endpoint, nesta ordem
+
+1. **Scaffold: só para domínio novo e só com ele na config.** O da referência sobrescreve, sem checar, entities, port, adapter, os dois módulos e os props/exec de cada domínio da config do gerador, e reescreve o agregador `common/surfaces/surface.module.ts` só com os domínios da config. Deixe na config apenas o domínio novo; depois restaure o agregador e acrescente só a linha nova na posição certa. Sem essa garantia, copie um domínio vizinho. O que ele gera é stub: body `.passthrough()` (aceita qualquer campo), response `z.unknown()` (o client recebe `unknown`), nomes de schema e imports fora do padrão. Critério: `git status` mostra só arquivos do domínio novo mais uma linha no agregador, e nenhum stub sobra.
+2. **entities**: schemas nomeados reutilizáveis (params, filtros, enum de sort, item e detalhe da resposta). Critério: todo schema exportado que vira tipo tem `.openapi('<Nome>')`.
+3. **props.surface** (`references/contract.md` §1) e a linha `import './surfaces/<acao>.<domain>.props.surface'` no `<domain>.surface.module.ts`, que é o que registra o contrato. Critério: o endpoint aparece no `openapi.json` gerado com `operationId` camelCase único e a `description` lista os `code` de 409/422.
+4. **service** + rules, access e errors, e os métodos que ele pede no **port** com tipos `*Row`/`*Record`/`New*`/`*Write` (`references/domain.md` §1–5). Critério: o service compila contra o port (em `check-types`, o único erro restante é o adapter ainda sem os métodos novos, resolvido no passo 5) e o port não importa do ORM nada além de enums e paginação; o caso de acesso negado sem escrita entra no spec do passo 8.
+5. **adapter** + `.sql.ts` e `-db-errors.ts` (`references/domain.md` §6–7); tabela ou coluna nova pela migration com `arch-db`. Critério: toda constraint que o write pode violar está no mapa de tradução.
+6. **exec.surface** (`references/contract.md` §3). Critério: path do decorator = `Endpoint` sem a barra; guards batem com `security`.
+7. **módulos**: exec em `controllers` e service em `providers` do `<domain>.surface.module.ts`; port novo ligado e exportado no `<domain>.sgbds.module.ts`; domínio novo no agregador (`references/domain.md` §8). Critério: a app sobe e a rota responde.
+8. **specs** (`references/review.md` §1). Critério: cada `code` novo tem teste que o afirma, o caso de acesso negado mostra o port de escrita sem chamada, e o retorno do service passa no `instructions.settings.response.body`.
+9. **`doc.md` e gate**: atualize a tabela endpoint x rota x permissão e as seções afetadas; rode `openapi:generate`, `check-types`, `lint` e os testes. Critério: tudo verde.
+
+Não crie o exec antes do contrato, nem o adapter antes do caso de uso. Formato por tipo de endpoint: `references/endpoints.md`.
+
+---
+
+## Matriz de decisão
+
+| Situação | Padrão | Template (`endpoints.md`) |
+|---|---|---|
+| Ler um recurso | service + `assert*` do access + port por id (e tenant) | 1.1 |
+| Lista de tela administrativa | offset com teto, sort `z.enum` + mapa, tiebreaker, `toPaginationMeta` | 1.2 |
+| Feed, log, linha do tempo | cursor keyset | 1.2 |
+| Criar com invariante | constraint + `-db-errors` -> 409/422 com `code` | 1.3 |
+| Criar com risco de duplicidade | `Idempotency-Key` + `IIdempotencyProvider` | 1.3 |
+| Atualizar parte | PATCH, `<Coisa>Write` campo a campo, `version` no `WHERE` | 1.4 |
+| Transição de estado | POST `/<id>/<acao>` + audit na mesma transação | 1.7 |
+| Multi-write no mesmo banco | um método do adapter com a transação dentro | 1.3, 1.7 |
+| Write + efeito externo que não pode se perder | outbox (`common/messaging`) | 1.12 |
+| Integração externa | port em `common/<capacidade>` ou `<x>.provider.port.ts` no domínio, com timeout | - |
+| Arquivo | capacidade de storage, rota própria | 1.8, 1.9 |
+| Sem autenticação | sem guard, `security: []`, rate limit revisado | 1.10 |
+| Pública que personaliza com token | `OptionalAuthUserGuard` | 1.10 |
+| Multi-tenant | ref de tenant do header resolvida no service + filtro em toda query | 1.11 |
+| Trabalho demorado | 202 + fila e worker | 1.12 |
+| Mudança de contrato | classificar patch/minor/major (`contract.md` §8) | - |
+| Decisão transversal | ADR (`review.md` §4) | - |
+
+---
+
+## Comandos
+
+Formas reais do repo de referência; descubra os nomes no `package.json` do seu.
+
+```bash
+<pm> run openapi:generate   # openapi.json + generated/openapi-client.d.ts a partir dos registries
+<pm> run check-types        # tsc --noEmit
+<pm> run lint               # linter/formatter do repo
+<pm> run test:unit          # e test:integration, test:e2e, test:load
+<pm> run prisma:generate    # ou o gerador do ORM do repo, depois de mudar o schema
+<pm> run migrate:create     # e migrate:up | down | validate (paridade migration x schema); regras em arch-db
+<pm> run seed               # runner de seed do repo
+<pm> run build
+# monorepo: <pm> --filter <app> <script>
+```
+
+Se um comando falhar por erro fora do escopo, registre e valide o que foi alterado.
+
+---
+
+## Anti-padrões
+
+Armadilhas que as regras acima não nomeiam; cada uma já quebrou algo.
+
+**Contrato**
+- `import type` de um props (no módulo, no build ou no script de geração): o TypeScript elide o import, o registro não roda e o endpoint some do `openapi.json` sem erro.
+- Contornar no client um `operationId` ruim ou um contrato errado: corrige-se aqui, regenera-se o documento e os clients.
+
+**Domínio**
+- Service que só repassa argumentos a outro: ou tem decisão, ou não existe.
+- Redeclarar em `providers` o service de outro domínio: segunda instância fora do grafo, estado e cache divergentes.
+- Autorização no exec ou num guard novo para regra que o access resolve: some do teste do service e do `doc.md`.
+- Exceções de 422 e de 409 com argumentos trocados: na referência a de 422 recebe o `code` primeiro e a de 409 a mensagem primeiro (`references/common.md` §4).
+
+**Dados**
+- Adapter que pega outro cliente no meio da transação: a escrita fica fora do `BEGIN` e o rollback não a alcança.
+
+**Segurança**
+- Senha mestra, coringa ou backdoor, ou comparação de senha fora do provider de hash (caminho legítimo em `references/security.md` §2).
+- Log de segredo ou PII (lista em `references/security.md` §8).
+
+**Processo**
+- Client gerado de um servidor rodando em vez do `openapi.json` do build: o client passa a refletir o deploy, não o código revisado.
+- Infra de teste sem specs: config de runner e relatório não são cobertura.
+
+---
+
+## Critério de aceite
+
+Uma alteração feita com esta skill só está pronta quando:
+
+- O endpoint funciona em runtime e o `openapi.json` gerado o representa (path, verbo, status, `security`, schemas nomeados, `code` de 409/422).
+- O exec é fino, o service concentra a decisão, o access autoriza o recurso e o port não carrega tipo de model do ORM.
+- Erros, paginação, datas e envelope seguem o helper único do repo.
+- Mudança de contrato, inclusive de `code`, está classificada (patch/minor/major, `references/contract.md` §8).
+- Specs cobrem o caminho feliz, cada `code` novo e o contrato da resposta.
+- `doc.md` do domínio reflete a mudança.
+- Geração do OpenAPI, typecheck, lint e testes passam.
+- O código não carrega nomes ou decisões de outro projeto sem validação explícita.
+- Item que não se aplica está registrado como "não aplicável" com motivo técnico.

package/.claude/skills/arch-api/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Arch Api"
+  short_description: "Implementa, revisa e refatora APIs NestJS contract-first - contrato OpenAPI por..."

package/.claude/skills/arch-api/references/common.md

@@ -0,0 +1,174 @@
+# `common/`: capacidades técnicas e infraestrutura compartilhada
+
+Abra ao criar ou usar uma capacidade de `common/` (mailer, storage, hash, segredos, mensageria, idempotência, tempo real), ao mexer em env, exceções, docs, observabilidade, utils ou no bootstrap. `common/` não conhece domínio: nada aqui importa de `modules/`, exceto o agregador de surfaces e os schemas cross-domain que o contrato exige (como a entidade do usuário autenticado).
+
+---
+
+## 1. Anatomia
+
+```txt
+common/<capacidade>/
+  ports/<capacidade>.<papel>.port.ts                    abstract class I<Capacidade><Papel> + tipos de entrada e saída
+  adapters/<tecnologia>.<capacidade>.<papel>.adapter.ts <Tecnologia><Capacidade><Papel>Adapter extends o port
+  <capacidade>.module.ts                                { provide: I<Capacidade><Papel>, useClass: <adapter> } + exports
+  <assunto>.service.ts | <assunto>.worker.ts            orquestração da capacidade, quando há (ex.: dispatcher, outbox)
+  templates/ | settings/                                o que a capacidade precisa e só ela usa
+```
+
+Papéis comuns: `provider` (faz algo para o domínio: enviar, gravar, hashear), `loader` (carrega algo no boot), `publisher` (emite eventos). Exemplos de forma (tecnologia é a do repo): `mailer.provider.port.ts` + `<tecnologia>.mailer.provider.adapter.ts`; `storage.provider.port.ts` + `<tecnologia>.storage.provider.adapter.ts`; `idempotency.provider.port.ts` + `db.idempotency.provider.adapter.ts`.
+
+Port ou classe concreta: na referência, hash, mailer, encrypters, storage, messaging, resilience, secrets e html têm port + adapter mesmo com uma implementação só; cache e fila são um service concreto; auth, environments (port + provider) e realtime (port + gateway) têm forma própria. Capacidade nova nasce com port quando um domínio a injeta (o port é o token de DI e o double do teste) ou quando a tecnologia pode trocar por env. Service concreto fica para cola de infraestrutura usada só por outras capacidades. Se o repo já resolveu a capacidade de outro jeito, siga o repo.
+
+---
+
+## 2. Adicionando uma capacidade
+
+```ts
+// common/mailer/ports/mailer.provider.port.ts
+export type MailSendInput = { to: string | string[]; subject: string; html: string; text?: string };
+
+export abstract class IMailerProvider {
+  abstract send(input: MailSendInput): Promise<void>;
+}
+```
+
+```ts
+// common/mailer/adapters/<tecnologia>.mailer.provider.adapter.ts
+@Injectable()
+export class SmtpMailerProviderAdapter extends IMailerProvider { // "Smtp": exemplo de tecnologia
+  private readonly logger = new Logger(SmtpMailerProviderAdapter.name);
+  private readonly from?: string;
+
+  constructor(private readonly env: IEnvironmentProvider) {
+    super();
+    this.from = env.get('MAIL_FROM_EMAIL');
+  }
+
+  async send(input: MailSendInput): Promise<void> {
+    if (!this.from) {
+      this.logger.warn('MAIL_FROM_EMAIL not configured; skipping email send');
+      return;
+    }
+    // chamada ao SDK ou cliente da tecnologia, com timeout (security.md §9)
+  }
+}
+```
+
+```ts
+// common/mailer/mailer.module.ts
+@Module({
+  providers: [{ provide: IMailerProvider, useClass: SmtpMailerProviderAdapter }, MailDispatcherService],
+  exports: [IMailerProvider, MailDispatcherService],
+})
+export class MailerModule {}
+```
+
+Passos:
+
+1. Port com a menor interface que o domínio precisa, em termos do domínio (`send`, `put`, `acquire`), sem tipo do SDK.
+2. Adapter `extends` o port, injeta `IEnvironmentProvider` para configuração e constrói o cliente da tecnologia no construtor. Critério: nenhum `process.env` no adapter.
+3. Toda env nova entra no schema (§3) com `describe`. Critério: o boot falha sem ela, ou o schema declara o default e o comportamento sem ela.
+4. Módulo liga port -> adapter e exporta o port (e o service de orquestração, se houver); o `app.module.ts` importa o módulo. Critério: a app sobe.
+5. Comportamento sem configuração é explícito: em dev, pular com `warn` é aceitável; em produção, decida fail-open ou fail-closed, registre no `describe` da env e, se fizer sentido, ofereça uma flag `..._FAIL_CLOSED`.
+6. Spec do adapter quando há tradução não trivial (montagem de cabeçalho, mapeamento de erro).
+
+O domínio injeta o port (`constructor(private readonly mailer: IMailerProvider)`) e o seu `surface.module` importa o módulo da capacidade, a menos que ela seja global.
+
+---
+
+## 3. `environments/`: env validado no boot
+
+```txt
+environments/environment.schema.ts       z.object({...}) com toda variável usada no código
+environments/environment.validate.ts     validateEnvironment: parse do schema; erro derruba o boot
+environments/ports/... + adapters/...    IEnvironmentProvider com get(chave) tipado
+environments/environment.module.ts
+server/app.module.ts                     ConfigModule.forRoot({ isGlobal: true, validate: validateEnvironment })
+```
+
+- Cada variável do schema (regra 15 do `SKILL.md`) tem `describe` dizendo o efeito e o default.
+- Número com `z.coerce.number()`; duração e limite com `.positive()`: `.default()` não dispara quando a chave existe e está vazia (`''` vira `0`), e um TTL zero passaria calado.
+- Boolean por literal: `z.preprocess((v) => v === 'true' || v === true, z.boolean())`; nunca `z.coerce.boolean()` (`'false'` vira `true`).
+- Enum de modo normalizado por `z.preprocess` (aliases como `PRODUCTION` -> forma canônica); quem compara o modo usa o valor normalizado (`security.md` §1).
+- Segredo com tamanho mínimo no schema.
+- Fora do bootstrap, leia env pelo provider; o `main.ts` é a exceção, porque roda antes da DI.
+
+---
+
+## 4. `http/`: enums e exceções
+
+- `http/enums/`: `http.status.success.{ok,created,noContent}`, `http.status.clientError.{badRequest,unauthorized,forbidden,notFound,conflict,unprocessableEntity}`, `http.header.{correlationId,idempotencyKey,...}`. Use o enum, nunca o número ou o nome de header solto.
+- `http/errors/`: exceções de domínio que saem no shape do contrato (`security.md` §7). Nenhuma camada abaixo do exec lança `BadRequestException('texto')` cru quando existe a exceção de domínio. Na referência:
+
+| Exceção | Status | Assinatura |
+|---|---|---|
+| `UnprocessableDomainException` | 422 | `(code, message, details?)` |
+| `ConflictDomainException` | 409 | `(message, code?)` |
+| `NotFoundDomainException` | 404 | `(message)` |
+| `ForbiddenCustomHttpException` | 403 | `(message)` |
+| exceção de 401 do repo | 401 | ver `unauthorized.custom.http.exceptions.ts` |
+
+Exceção nova: `security.md` §7.
+
+---
+
+## 5. `docs/openapi/` e `schemas/`
+
+- `docs/openapi/`: `registries.docs.ts` (lista global), `response.docs.ts` (blocos de erro), `build.ts` (documento), `generate.ts` (grava o arquivo) e, se o repo tiver, um passo de enriquecimento das extensões `x-*`. Mecânica em `contract.md` §2.
+- `schemas/`: `paginations.ts` (`paginationQuery`, `paginatedResponse`, `toPaginationMeta`), `errors.ts` (shape de erro por status), entidades usadas por vários domínios e o setup do Zod com OpenAPI. Schema de um domínio só fica no módulo dele.
+
+---
+
+## 6. `sgbds/`: o módulo global de banco
+
+```txt
+sgbds/containers/sgbds.module.ts    @Global(); providers e exports: os serviços de banco (na referência, ORM e driver)
+sgbds/settings/                     schema do ORM, serviços de banco, db-errors.ts (rethrowDbError), runner de seed
+sgbds/ports/  sgbds/adapters/<orm>/ repositório base genérico (CRUD) e IPaginatedResult
+sgbds/generated/                    client gerado pelo ORM: nunca editar à mão
+sgbds/migrations/                   <timestamp>_<NNNN>_<nome>.ts com up e down (ferramenta do repo)
+sgbds/seeds/                        <timestamp>-<Nome>.ts + dataset/ + README
+```
+
+- O módulo é global; adapters injetam os serviços que ele exporta (regra 11 do `SKILL.md`).
+- O serviço do ORM conecta em `onModuleInit` sem engolir erro (falhar no boot é melhor que subir saudável e devolver 500) e fixa limites de transação interativa (espera e duração máximas) para uma transação presa não segurar conexão.
+- Na referência há dois clientes exportados: ORM para escrita e driver para leitura quente. `arch-db` recomenda um pool por processo e vence no dimensionamento (reference `pooling-ops.md` de lá): se cada cliente abre o seu pool, some os dois no orçamento de conexões; não crie um terceiro.
+- O repositório base genérico é o que o scaffold usa; domínio com regra declara métodos próprios (`domain.md` §5).
+- Migrations, seeds, schema, índices e pool: `arch-db`. Aqui só a fiação.
+
+---
+
+## 7. `observability/`, `guards/`, `decorators/`, `policies/`
+
+- `observability/`: interceptor de correlação (lê o header de correlação ou gera um id e loga o desfecho da request), filter de exceções, logger estruturado e o módulo. Campos e limites em `security.md` §8.
+- `guards/`: autenticação (`AuthUserGuard`, que estende o guard do passport com a estratégia JWT de `common/auth/`), autenticação opcional e rate limit por tipo de rota. Regras em `security.md` §3.
+- `decorators/`: usuário autenticado, `Zd*` (validação com o schema do contrato) e contexto HTTP. Tabela em `contract.md` §4.
+- `policies/`: ownership transversal (`assertResourceOwner(owner, actorId, message?)` lança 403). Autorização por recurso de um domínio fica no `<domain>-access.ts` dele.
+- `auth/`: estratégia JWT, catálogo de permissões (`permissions.ts`) e validade de sessão.
+
+---
+
+## 8. `utils/<tipo>/`
+
+Helpers puros agrupados por tipo (`array`, `http`, `json`, `pagination`, `sql`, `string` ...): `utils/<tipo>/<nome>.<tipo>.util.ts` (maioria; siga o vizinho da pasta), teste `*.unit.spec.ts`, exportados pelo `index.ts` da pasta. Exemplos: `utils/string/interpolate.string.util.ts`, `utils/array/remove-duplicated-objects.array.util.ts`; algumas pastas usam o nome sem o tipo (o escape de curingas para `ILIKE` em `utils/sql/`), e o arquivo novo segue a pasta onde entra. Util não injeta nada e não conhece domínio; se precisa de DI, é capacidade (§2).
+
+---
+
+## 9. `server/`: bootstrap
+
+`app.module.ts` importa `ConfigModule` com a validação de env, o módulo global de banco, os módulos de capacidade e o `SurfaceModule`. `main.ts`, nesta ordem:
+
+```txt
+imports de efeito colateral   setup do Zod com OpenAPI e extensões globais do repo
+segredos                      loader de segredos antes do NestFactory, para o schema de env validar já com eles
+NestFactory.create            CORS por lista do env (credentials), logger
+prefixo global                ex.: api/v1, que é o mesmo do servers do documento
+body parser                   limite explícito
+x-powered-by                  desligado
+trust proxy                   pelo parser do repo (server/trust-proxy.ts + spec), default loopback
+helmet                        CSP desligada só se a API não serve HTML além da UI de docs
+docs                          SwaggerModule.setup só quando a exposição está ligada (fail-closed)
+listen                        porta do env
+```
+
+As regras de cada linha (CORS, `trust proxy`, limite de body, docs fail-closed, comparação do modo) estão em `security.md` §1.