# Auditoria — afirmações de estado na documentação **Data:** 2026-08-14 · **Medido contra:** `origin/main` @ `840917ed` **Método:** 11 agentes em paralelo, um por grupo de documento, cada um extraindo toda frase que afirma como o mundo *está* e medindo-a contra a fonte com um comando real. Depois dois passes adversariais: um tentando derrubar os vereditos "VERDADEIRA", outro caçando o que ninguém olhou. **Resultado:** 393 afirmações medidas · 166 confirmadas · 227 com problema · 4 vereditos "VERDADEIRA" derrubados · 19 achados em documentos não cobertos. --- ## Como usar este documento **Cada achado traz o comando que o mede. É o comando que vale, não o veredito.** Este relatório é uma fotografia de 2026-08-14 e envelhece exatamente como o que ele critica — quem for tratar um achado **roda o comando de novo** antes de confiar na linha. A triagem é **por tipo de documento**, não por gravidade: | Tipo | O que fazer | |---|---| | **Autoridade** — doutrina, ADR, runbooks, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, READMEs | Consertar. E onde a afirmação puder virar **comando**, trocar em vez de corrigir: número corrigido envelhece de novo, `rode isto para saber` não envelhece. | | **Retrato** — `docs/current-state.md`, `docs/harness-audit.md` | **Não corrigir as contagens.** Carimbar no topo o SHA e a data contra os quais os números conferem, e parar de manter. Documento honestamente datado nunca mente; documento atualizado uma vez volta a mentir. | | **Registro** — `CHANGELOG.md` | Cada seção descreve uma versão e é histórica por natureza. Só se corrige o que afirma sobre **aquela** versão e é falso. | | **Planejamento** — `docs/stories/`, `docs/handoffs/`, `docs/specs/` | Deixar como está. Registro histórico pode apontar para o que nunca existiu; os 385 ponteiros mortos do repo vivem aí, e o gate os exclui de propósito. | O gate `tests/unit/documentacao-aponta-para-o-que-existe.test.ts` impede a reincidência das duas piores formas (ponteiro morto e nota de pendência sobrevivente) nos documentos de autoridade. O resto é dívida que decai sozinha se ninguém alimentar. --- # AUTORIDADE — 152 achados ## `AGENTS.md` — 22 ### L24 · FALSA · gravidade alta · sobre-o-codigo > WAHA Plus (engine NOWEB) **Mede com:** ```bash sed -n '110,152p' docker-compose.prod.yml ``` **Deu:** ``` image: ${WAHA_IMAGE:-devlikeapro/waha:latest-2026.7.2} # Core grátis por padrão; troque para devlikeapro/waha-plus via WAHA_IMAGE se # precisar de multi-número/retry/S3 (licença paga). WHATSAPP_DEFAULT_ENGINE: ${WHATSAPP_DEFAULT_ENGINE:-NOWEB} ``` **Sugestão:** WAHA (engine NOWEB; o `docker-compose.prod.yml` entrega **Core** por padrão — `devlikeapro/waha`. Plus é opt-in por `WAHA_IMAGE=devlikeapro/waha-plus`, e é o que habilita multi-número/retry/S3). Confira: `grep -n 'WAHA_IMAGE' docker-compose.prod.yml`. **Vira teste:** tests/unit: o default de WAHA_IMAGE em docker-compose.prod.yml e a palavra usada em AGENTS.md/CLAUDE.md concordam (Core vs Plus) ### L26 · FALSA · gravidade alta · pendencia > o job `ci` roda 22, mas o `perf` ainda builda em 20 — divergência com `engines`, registrada como bug **Mede com:** ```bash grep -rn "node-version" .github/workflows/ ``` **Deu:** ``` .github/workflows/perf.yml:22: node-version: 22 .github/workflows/ci.yml:19: node-version: 22 .github/workflows/ci.yml:69: node-version: 22 .github/workflows/e2e.yml:164: node-version: 22 (perf.yml traz o comentário: "# 22 como o job `ci` e o `.nvmrc`. Buildar numa versão que o `engines` (>=22) não suporta esconde quebra ou inventa falha.") ``` **Sugestão:** Runtime: **Node ≥22** (`.nvmrc` = 22; todos os jobs de CI fixam a mesma versão). Confira: `grep -rn 'node-version' .github/workflows/`. **Vira teste:** tests/unit: todo `node-version:` em .github/workflows/ é igual ao conteúdo de .nvmrc ### L28 · FALSA · gravidade alta · data-versao > Versão do produto: **1.0.0** (`CHANGELOG.md`, SemVer — mudança que afeta quem roda VPS entra lá). **Mede com:** ```bash grep -nE '^## \[' CHANGELOG.md | head -6 ; git tag --list | tail -6 ; node -e "console.log(require('./package.json').version)" ``` **Deu:** ``` 9:## [Não lançado] 11:## [1.3.0] — 2026-08-13 72:## [1.2.1] — 2026-08-12 117:## [1.2.0] — 2026-08-11 258:## [1.1.0] — 2026-07-30 280:## [1.0.0] — 2026-07-27 tags: v1.0.0 v1.1.0 v1.1.1-jmpo.1 v1.2.0 v1.2.1 v1.3.0 package.json version: 0.1.0 ``` **Sugestão:** Versão do produto: a última **lançada** é o topo de `CHANGELOG.md` (`grep -m2 -E '^## \[' CHANGELOG.md`) e tem tag git correspondente (`git tag --list 'v*' | tail -1`). SemVer — mudança que afeta quem roda VPS entra lá. (`package.json` segue em `0.1.0` e **não** é a fonte da versão do produto.) **Vira teste:** tests/unit: a versão do topo de CHANGELOG.md tem uma tag git `v` correspondente ### L34 · FALSA · gravidade media · contagem > 166 route handlers REST (versionado por path) — 169 contando `app/api/**` **Mede com:** ```bash git ls-files 'app/api/v1/**/route.ts' | wc -l ; git ls-files 'app/api/**/route.ts' | wc -l ; git ls-tree -r 741c4ec8 --name-only | grep -cE '^app/api/v1/.*/route\.ts$' ``` **Deu:** ``` 201 203 (no SHA 741c4ec8 que o doc cita noutro bloco: 200) ``` **Sugestão:** route handlers REST versionados por path — reconte com `git ls-files 'app/api/v1/**/route.ts' | wc -l` (e `git ls-files 'app/api/**/route.ts' | wc -l` para o total de `app/api/**`). ### L54 · FRAGIL · gravidade baixa · sobre-o-codigo > pnpm test:unit # vitest — EXCLUI tests/invariants e tests/e2e **Mede com:** ```bash sed -n '25,33p' vitest.config.ts ``` **Deu:** ``` exclude: [ "**/node_modules/**", ".next", "dist", ".claude/**", "tests/e2e/**", "tests/invariants/**", "tests/journeys/**", ] ``` **Sugestão:** pnpm test:unit # vitest — EXCLUI tests/invariants, tests/e2e e tests/journeys (lista viva em `vitest.config.ts → exclude`) ### L57 · FALSA · gravidade media · sobre-o-codigo > pnpm gov:verify # typecheck + lint + test:unit ← verificação única atual **Mede com:** ```bash node -e "console.log(require('./package.json').scripts['gov:verify'])" ``` **Deu:** ``` pnpm typecheck && pnpm lint && pnpm lint:channels && pnpm test:unit ``` **Sugestão:** pnpm gov:verify # typecheck + lint + lint:channels + test:unit ← verificação única atual # (confira o encadeamento real: `node -e \"console.log(require('./package.json').scripts['gov:verify'])\"`) **Vira teste:** tests/unit: a lista de passos descrita em AGENTS.md/CLAUDE.md para `gov:verify` bate com o script em package.json ### L64 · FALSA · gravidade alta · sobre-o-codigo > `.github/workflows/ci.yml`: `verify` = typecheck + lint + test:unit **Mede com:** ```bash sed -n '9,58p' .github/workflows/ci.yml ``` **Deu:** ``` Steps do job `verify`: Typecheck (pnpm typecheck) · Lint (pnpm lint) · Channel provider leak (pnpm lint:channels) · Unit tests (pnpm test:unit) · Kit self-host (bash) (pnpm test:shell) — cinco passos, não três. ``` **Sugestão:** `.github/workflows/ci.yml`: `verify` = typecheck + lint + lint:channels + test:unit + test:shell (**cinco** passos — `pnpm lint` sozinho não cobre `lint:channels` nem o kit self-host). Reconfira com `awk '/^ verify:/,/^ invariants:/' .github/workflows/ci.yml | grep -A1 'name:'`. **Vira teste:** tests/unit: os passos `run:` do job verify de ci.yml estão todos citados no bloco de CI de AGENTS.md ### L67 · FALSA · gravidade alta · contagem > roda **45 das 46 specs** Playwright contra um Supabase local de verdade **Mede com:** ```bash ls tests/e2e/*.spec.ts | wc -l ; awk '/^ SPECS_PARTE_1:/{f=1;next} /^ SPECS_PARTE_2:/{f=0} f' .github/workflows/e2e.yml | grep -coE '[a-z0-9-]+\.spec\.ts' ; awk '/^ SPECS_PARTE_2:/{f=1;next} /^ # Cada item aqui/{f=0} f' .github/workflows/e2e.yml | grep -coE '[a-z0-9-]+\.spec\.ts' ``` **Deu:** ``` disco = 48 SPECS_PARTE_1 = 25 SPECS_PARTE_2 = 22 FORA_DO_CI = 1 rodam = 47, soma = 48 (bate com o disco) ``` **Sugestão:** roda **todas as specs Playwright menos as declaradas em `FORA_DO_CI`** contra um Supabase local de verdade com o `baseline.sql` aplicado. O número não vai escrito aqui de propósito — ele já apodreceu quatro vezes. Meça: `ls tests/e2e/*.spec.ts | wc -l` (disco) e `echo $SPECS_PARTE_1 $SPECS_PARTE_2 | wc -w` nas listas de `.github/workflows/e2e.yml`. **Vira teste:** tests/unit: SPECS_PARTE_1 + SPECS_PARTE_2 + FORA_DO_CI == ls tests/e2e/*.spec.ts (o repo já tem tests/unit/e2e-cobertura-completa.test.ts para a soma; falta o gate sobre o NÚMERO citado nos docs) ### L69 · FRAGIL · gravidade media · ativo-obrigatorio > **É check obrigatório desde 2026-08-08.** **Mede com:** ```bash gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(", ")' ; sed -n '10,17p' .github/workflows/e2e.yml ``` **Deu:** ``` verify, build-and-size, invariants, e2e, imagens-ok (mas o cabeçalho do PRÓPRIO e2e.yml ainda afirma o contrário: "# NÃO-BLOQUEANTE por ausência, não por mordaça: `e2e` não está na lista de checks obrigatórios da branch protection, então falhar aqui não segura merge.") ``` **Sugestão:** É check obrigatório — confirme antes de citar: `gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts'`. (A data de ativação não é auditável pelo repo; e o cabeçalho de `.github/workflows/e2e.yml` ainda diz que o `e2e` NÃO é obrigatório — esse comentário está podre e contradiz a branch protection.) **Vira teste:** tests/unit: nenhum comentário em .github/workflows/ afirma que um check está fora dos obrigatórios sem bater com a lista da branch protection (ou, mais simples: o texto 'não está na lista de checks obrigatórios' não aparece em e2e.yml) ### L114 · FALSA · gravidade media · contagem > **`lib/supabase/admin.ts`** — service role **bypassa RLS**. 89 rotas o usam **Mede com:** ```bash grep -rl "createAdminClient" app/api --include='route.ts' | wc -l ; git ls-files 'app/api/**/route.ts' | wc -l ``` **Deu:** ``` 119 203 ``` **Sugestão:** **`lib/supabase/admin.ts`** — service role **bypassa RLS**. Boa parte dos handlers de `app/api/**` o usa (reconte: `grep -rl createAdminClient app/api --include=route.ts | wc -l` contra `git ls-files 'app/api/**/route.ts' | wc -l`); toda query precisa filtrar `organization_id` manualmente, resolvido de fonte confiável (cookie/JWT/webhook secret/path token), **nunca do body**. ### L130 · FALSA · gravidade baixa · contagem > `lib/database.types.ts` (6.1k linhas — gerado do schema Supabase) **Mede com:** ```bash wc -l < lib/database.types.ts ``` **Deu:** ``` 7023 ``` **Sugestão:** `lib/database.types.ts` (gerado do schema Supabase — `wc -l lib/database.types.ts` se quiser o tamanho de hoje) ### L131 · FRAGIL · gravidade baixa · ponteiro > `graphify-out/` (grafo de conhecimento; regenerado por `/graphify .`) **Mede com:** ```bash test -d graphify-out && echo existe || echo ausente ; grep -n graphify .gitignore ``` **Deu:** ``` ausente 100:# graphify (análise local de knowledge graph) 101:graphify-out/ ``` **Sugestão:** `graphify-out/` (grafo de conhecimento local; ignorado pelo git e **ausente num clone fresco** — só existe depois de rodar `/graphify .`) ### L153 · FRAGIL · gravidade media · contagem > **257** arquivos de teste unitário em `tests/unit/` ... O repo tem **491** arquivos `*.test.ts(x)` no total **Mede com:** ```bash git ls-files 'tests/unit/*.test.ts' 'tests/unit/*.test.tsx' | wc -l ; git ls-files '*.test.ts' '*.test.tsx' | wc -l ; git ls-tree -r 741c4ec8 --name-only | grep -cE '^tests/unit/.*\.test\.tsx?$' ; git rev-list --count 741c4ec8..HEAD ``` **Deu:** ``` HEAD (840917ed): 264 e 511 741c4ec8 (o SHA declarado): 257 e 491 commits desde o SHA declarado: 45 ``` **Sugestão:** Arquivos de teste unitário em `tests/unit/` e no repo inteiro — **conte, não cite**: `git ls-files 'tests/unit/*.test.ts' 'tests/unit/*.test.tsx' | wc -l` e `git ls-files '*.test.ts' '*.test.tsx' | wc -l`. A diferença vive junto ao código, fora de `tests/`, e também roda em `test:unit`. ### L154 · FRAGIL · gravidade baixa · contagem > **102** arquivos de invariante de banco em `tests/invariants/` **Mede com:** ```bash git ls-files 'tests/invariants/*.test.ts' | wc -l ; git ls-tree -r 741c4ec8 --name-only | grep -cE '^tests/invariants/.*\.test\.ts$' ``` **Deu:** ``` HEAD: 103 741c4ec8: 102 ``` **Sugestão:** Arquivos de invariante de banco em `tests/invariants/` (`git ls-files 'tests/invariants/*.test.ts' | wc -l`) — RLS/isolamento cross-tenant, RBAC, governança (G1–G6). Excluídos do `test:unit` de propósito; rodam via `pnpm test:db` **e no job `invariants` do CI**. ### L157 · FALSA · gravidade alta · contagem > **46** specs Playwright em `tests/e2e/` (`ls tests/e2e/*.spec.ts | wc -l`). **45 rodam no CI** **Mede com:** ```bash ls tests/e2e/*.spec.ts | wc -l ; awk '/^ FORA_DO_CI:/{f=1;next} /^ steps:/{f=0} f' .github/workflows/e2e.yml | grep -oE '[a-z0-9-]+\.spec\.ts' ``` **Deu:** ``` 48 no disco; 47 nas listas de execução; FORA_DO_CI = vps-fresh-onboarding.spec.ts (1) ``` **Sugestão:** Specs Playwright em `tests/e2e/` — **reconte antes de citar** (`ls tests/e2e/*.spec.ts | wc -l`), e o quanto disso roda no CI sai de `echo $SPECS_PARTE_1 $SPECS_PARTE_2 | wc -w` em `.github/workflows/e2e.yml` (**check obrigatório**). A única de fora está declarada em `FORA_DO_CI` — hoje `vps-fresh-onboarding`, por dependência de serviço externo (WAHA/Redis/Resend/Nuvemshop). **Vira teste:** tests/unit: nenhum número literal de specs e2e sobrevive em AGENTS.md/CLAUDE.md sem bater com `ls tests/e2e/*.spec.ts | wc -l` ### L159 · FRAGIL · gravidade media · ponteiro > Ver issue #63. **Mede com:** ```bash gh issue view 63 --repo melgarafael/DeskcommCRM --json number,title,state ``` **Deu:** ``` {"number":63,"state":"CLOSED","title":"E2E: 3 das 33 specs fora do CI (inclui a vps-fresh-onboarding, P0) + e2e ainda não é gate"} ``` **Sugestão:** A exclusão e o motivo medido vivem no bloco `FORA_DO_CI` de `.github/workflows/e2e.yml` — a issue #63, que originou a discussão, está **fechada** e seu título descreve um estado que já não vale ("3 das 33 specs", "e2e ainda não é gate"). ### L161 · FRAGIL · gravidade media · data-versao > ## Limitações conhecidas (estado em 2026-07-29, contra `origin/main` @ 789dfa6) **Mede com:** ```bash git log --oneline -1 789dfa6 ; git rev-list --count 789dfa6..HEAD ``` **Deu:** ``` 789dfa6f fix(audit): nenhuma acao via MCP era auditada, e o silencio escondia isso (o cabeçalho declara 2026-07-29, mas o próprio bloco traz uma correção datada de 2026-08-14 na linha 166 — o SHA declarado não descreve o conteúdo do bloco) ``` **Sugestão:** ## Limitações conhecidas > Cada item abaixo carrega o comando que o mede. Um item sem comando é suspeito de estar podre — meça antes de repassar. A régua de datar o bloco inteiro num SHA foi abandonada: os itens envelhecem em ritmos diferentes e o cabeçalho passava a mentir por todos eles. ### L163 · FALSA · gravidade media · contagem > **1 das 46 specs E2E segue fora do CI** (`vps-fresh-onboarding`), e o `e2e` **é** check obrigatório desde 2026-08-08 **Mede com:** ```bash ls tests/e2e/*.spec.ts | wc -l ; gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(", ")' ``` **Deu:** ``` 48 verify, build-and-size, invariants, e2e, imagens-ok ``` **Sugestão:** **Exatamente 1 spec E2E segue fora do CI** (`vps-fresh-onboarding` — a lista viva é `FORA_DO_CI` em `.github/workflows/e2e.yml`), e o `e2e` **é** check obrigatório. Ou seja: um PR que quebre o `e2e` não entra — mas a jornada de instalação fresca, que é o produto que se vende, continua sem gate. Se você mexeu nela, a prova é sua. ### L168 · FALSA · gravidade alta · pendencia > Rate limit HTTP existe em **2** pontos do código (webhook de captação e dispatcher de IA); login, signup, aceite de convite, crons e MCP estão sem. Não há lockout por conta no login. **Mede com:** ```bash grep -rn 'auth/rate-limit' app/ lib/ proxy.ts --include='*.ts' --include='*.tsx' | grep -v '\.test\.' ; grep -n 'contaBloqueadaPorFalhas\|registrarFalhaDeLogin' app/actions/auth/signInWithPassword.ts ; sed -n '136,142p' lib/auth/rate-limit.ts ``` **Deu:** ``` app/team/accept-invite/[token]/page.tsx:14:import { authRateLimited, AUTH_LIMITS } app/actions/auth/signUp.ts:14:import { authRateLimited, AUTH_LIMITS } app/actions/auth/requestPasswordReset.ts:8:import { authRateLimited, AUTH_LIMITS } app/actions/auth/signInWithPassword.ts:13: contaBloqueadaPorFalhas / 14: registrarFalhaDeLogin / 58: (await authRateLimited("login", null, AUTH_LIMITS.login)) || (await contaBloqueadaPorFalhas(...)) / 78: await registrarFalhaDeLogin(...) AUTH_LIMITS = { login: {ip: loginIpLimit(), id: 5, windowSec: 300}, signup: {ip:20, windowSec:3600}, reset: {ip:30, id:3, windowSec:3600}, invite_accept: {ip:60, windowSec:3600} } (além disso: app/api/v1/webhooks/in/[token]/ ``` **Sugestão:** Rate limit HTTP cobre hoje o webhook de captação, o dispatcher de IA e as quatro portas de auth — login, signup, recuperação de senha e aceite de convite (`AUTH_LIMITS` em `lib/auth/rate-limit.ts`). **Há** lockout por conta no login: 5 senhas erradas na mesma conta em 5 min trancam a janela, inclusive contra ataque distribuído por muitos IPs (`contaBloqueadaPorFalhas` / `registrarFalhaDeLogin`, chamados em `app/actions/auth/signInWithPassword.ts`). Continuam sem limitador: crons e MCP. Reconfira quem importa o módulo: `grep -rn 'auth/rate-limit' app/ lib/ --include='*.ts*' | grep -v '\.test\.'`. **Vira teste:** tests/unit: signInWithPassword chama contaBloqueadaPorFalhas antes do provedor e registrarFalhaDeLogin depois de senha errada (guarda o comportamento, não o nome) ### L170 · FRAGIL · gravidade media · sobre-o-codigo > Fallback do rate limit é **em memória** — sem Upstash configurado o limite é por processo. **Mede com:** ```bash grep -n 'UPSTASH' lib/env.ts ; sed -n '44,62p' lib/ai/dispatcher/rate-limit.ts ``` **Deu:** ``` lib/env.ts:83: UPSTASH_REDIS_REST_URL: required("UPSTASH_REDIS_REST_URL"), lib/env.ts:84: UPSTASH_REDIS_REST_TOKEN: required("UPSTASH_REDIS_REST_TOKEN"), comentário do próprio módulo: "A versão anterior dizia que as duas variáveis do Upstash são 'opcionais no kit self-host, então sem elas este é o caminho normal': falso, e medido — `lib/env.ts:83-84` as declara `required()`, o app não sobe sem elas. O que de fato leva para cá é Redis INALCANÇÁVEL com a variável presente" ``` **Sugestão:** Fallback do rate limit é **em memória** — mas o gatilho não é "sem Upstash configurado": `lib/env.ts` declara as duas variáveis do Upstash como `required()` e o app não sobe sem elas. O que cai para a memória é **Redis inalcançável com a variável presente** (contêiner `srh` parado, rede caída, URL errada) — e aí o limite passa a ser por processo. ### L172 · FALSA · gravidade alta · pendencia > **6 vars de `lib/env.ts` faltam no `.env.example`**, incluindo 3 secrets. **Mede com:** ```bash comm -23 <(grep -oE '^\s{2}[A-Z][A-Z0-9_]+:' lib/env.ts | tr -d ' :' | sort -u) <(grep -oE '^[A-Z][A-Z0-9_]+' .env.example | sort -u) ``` **Deu:** ``` NODE_ENV (45 chaves em lib/env.ts; 54 no .env.example; única ausente é NODE_ENV, que não é secret nem var de configuração do operador. Spot-check dos secrets: AI_CRED_AES_KEY:40, CPF_ENCRYPTION_KEY:33, LGPD_SIGNING_KEY:132, IMPERSONATE_COOKIE_SECRET:124, NUVEMSHOP_OAUTH_ENCRYPTION_KEY:35, WAHA_BYO_ENCRYPTION_KEY:37, INTERNAL_SECRET:18, INTERNAL_CRON_SECRET:20, WAHA_HMAC_SECRET:50 — todos presentes) ``` **Sugestão:** Toda var de `lib/env.ts` está no `.env.example` exceto `NODE_ENV` (que o runtime define, não o operador). Se você adicionar env var, adicione nos dois lugares (item 9 do DoD) — e confira com `comm -23 <(grep -oE '^\s{2}[A-Z][A-Z0-9_]+:' lib/env.ts | tr -d ' :' | sort -u) <(grep -oE '^[A-Z][A-Z0-9_]+' .env.example | sort -u)`. **Vira teste:** tests/unit: toda chave do schema de lib/env.ts aparece em .env.example (allowlist explícita para NODE_ENV) — gate que substitui a contagem em prosa ### L176 · FALSA · gravidade media · contagem > **89 dos 169 handlers de `app/api/**` usam service role** — sem gate automático para o filtro de `organization_id` **Mede com:** ```bash grep -rl "createAdminClient" app/api --include='route.ts' | wc -l ; git ls-files 'app/api/**/route.ts' | wc -l ``` **Deu:** ``` 119 203 ``` **Sugestão:** Boa parte dos handlers de `app/api/**` usa service role — **sem gate automático** para o filtro de `organization_id`. Meça hoje: `grep -rl createAdminClient app/api --include=route.ts | wc -l` de `git ls-files 'app/api/**/route.ts' | wc -l`. Escrevendo handler novo, o filtro é responsabilidade sua. ## `CLAUDE.md` — 14 ### L8 · FALSA · gravidade media · contagem > índice dos 149 docs **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && git ls-files 'docs/**/*.md' | wc -l && git ls-files 'docs/*.md' 'docs/**/*.md' | sort -u | wc -l && sed -n '13p' docs/index.md ``` **Deu:** ``` Régua declarada pelo próprio índice (`git ls-files 'docs/**/*.md' | wc -l`): 151. Contando também os 10 `.md` da raiz de docs/ (`git ls-files 'docs/*.md' 'docs/**/*.md' | sort -u | wc -l`): 161. docs/index.md:13 ainda diz "Mapa dos **149** arquivos `.md` de `docs/`, espalhados por **24** subpastas" — e `find docs -mindepth 1 -type d | wc -l` devolve 30. O cabeçalho do índice declara `audited_against: origin/main @ 789dfa6 (v1.0.0, 2026-07-27)`. ``` **Sugestão:** - [`docs/index.md`]\(docs/index.md\) — índice dos docs de `docs/`, com regra de precedência quando dois docs discordam. Use antes de sair varrendo `docs/`. **O total citado lá dentro está congelado em 2026-07-27** — se precisar do número, conte: `git ls-files 'docs/*.md' 'docs/**/*.md' | sort -u | wc -l`. **Vira teste:** tests/unit/doc-index.test.ts: extrair o número em negrito de docs/index.md:13 e comparar com a régua que a própria linha declara; reprovar na divergência. ### L31 · FALSA · gravidade media · sobre-o-codigo > **Rate limit:** Upstash Redis sliding window **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && sed -n '17,20p' lib/auth/rate-limit.ts && sed -n '4p' lib/ai/dispatcher/rate-limit.ts ``` **Deu:** ``` lib/auth/rate-limit.ts:17-19: "Janela FIXA (é o que `checkRateLimit` implementa: `INCR` + `EXPIRE`), então uma rajada na virada da janela passa em dobro." lib/ai/dispatcher/rate-limit.ts:4: "Fixed-window counter on Upstash Redis: `ai-runs::` with …". Nenhuma implementação de sliding window na superfície de rate limit. ``` **Sugestão:** - **Rate limit:** contador de **janela fixa** em Upstash Redis (`INCR` + `EXPIRE`, `lib/ai/dispatcher/rate-limit.ts`), com degradação para contador em memória do processo quando Upstash não está configurado. Janela fixa deixa passar rajada na virada — é limite de abuso, não de precisão. Sliding window nunca foi implementado; onde os docs antigos dizem isso, eles copiaram o PRD. ### L32 · FRAGIL · gravidade baixa · data-versao > strings tipo `"anthropic/claude-sonnet-4-6"` **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && sed -n '24,34p' lib/ai/gateway.ts ``` **Deu:** ``` lib/ai/gateway.ts:24-33 — `export type ModelId = "anthropic/claude-sonnet-5" | "anthropic/claude-opus-5" | "anthropic/claude-haiku-4-5" | "openai/text-embedding-3-small" | (string & {})`; `DEFAULT_BOT_MODEL = "anthropic/claude-sonnet-5"`. O ID citado no doc (`claude-sonnet-4-6`) não está mais na união canônica — sobrevive só em fixtures de teste (lib/followup/plano-de-tempo.test.ts) e no comentário do próprio gateway.ts:5. ``` **Sugestão:** - **AI:** Vercel AI Gateway (Anthropic primário; OpenAI backup pra embeddings). Os IDs canônicos vivem na união `ModelId` de `lib/ai/gateway.ts` — leia lá em vez de copiar um exemplo daqui; hoje o default de chat é `DEFAULT_BOT_MODEL`. ### L49 · FALSA · gravidade alta · sobre-o-codigo > POSTs de criação na API aceitam header `Idempotency-Key: ` (TTL 24h via Upstash) **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && grep -rln 'export async function POST' app/api/v1/ | wc -l && grep -rln 'Idempotency-Key' app/api/v1/ && grep -rn 'redis|upstash' 'app/api/v1/lgpd/requests/[id]/approve/route.ts' ``` **Deu:** ``` 95 arquivos de rota declaram POST em app/api/v1/. Exatamente 1 lê o header: app/api/v1/lgpd/requests/[id]/approve/route.ts (linhas 41-45). E ele NÃO usa Upstash — persiste na tabela Postgres `idempotency_keys` (linha 81: `.from("idempotency_keys")`). Grep por redis/upstash nesse arquivo: 0 ocorrências. ``` **Sugestão:** - Idempotência de POST **não é geral**: hoje só `POST /api/v1/lgpd/requests/{id}/approve` exige `Idempotency-Key`, e ele grava na tabela Postgres `idempotency_keys` (não em Upstash). Antes de assumir que sua rota nova herda isso, meça: `grep -rln 'Idempotency-Key' app/api/v1/`. Estender para os demais POSTs de criação é trabalho em aberto, não estado atual. ### L56 · FALSA · gravidade alta · sobre-o-codigo > Paginação: cursor opaco base64+HMAC por default **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && grep -rn 'base64url' app/api/v1/leads/_handler.ts app/api/v1/messages/_handler.ts && for f in app/api/v1/messages/_handler.ts app/api/v1/leads/_handler.ts app/api/v1/admin/inbox/conversations/route.ts; do printf '%s createHmac=' $f; grep -c createHmac $f; done && grep -rln createHmac app/api/v1/ ``` **Deu:** ``` leads/_handler.ts:125 e messages/_handler.ts:143 decodificam com `JSON.parse(Buffer.from(raw,"base64url").toString("utf8"))` — JSON em base64url, sem assinatura. createHmac = 0 nos três handlers de cursor. Em toda a app/api/v1 só 3 arquivos usam createHmac, e os três são webhooks da Nuvemshop (store-redact, customer-data-request, customer-redact). ``` **Sugestão:** - Paginação: cursor opaco em **base64url de um JSON** — hoje **sem HMAC**. O cursor é adivinhável e forjável; trate-o como entrada não confiável e valide o payload decodificado antes de usar. Assinar o cursor é dívida aberta, não o estado do código: `grep -rln createHmac app/api/v1/` devolve só os webhooks da Nuvemshop. **Vira teste:** tests/unit/cursor-assinado.test.ts: montar um cursor com base64url(JSON) alterado à mão e afirmar que o handler o REJEITA. Hoje ele nasce vermelho — é a catraca que segura a correção. ### L60 · FALSA · gravidade media · sobre-o-codigo > Rate limit headers: `X-RateLimit-*` + `Retry-After` em 429 **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && grep -rin 'x-ratelimit' --include='*.ts' --include='*.tsx' . | grep -v node_modules && grep -rn 'Retry-After' --include='*.ts' lib/ app/ | grep -v test ``` **Deu:** ``` `X-RateLimit` não aparece em NENHUM arquivo .ts/.tsx do repo — só em CLAUDE.md:60, docs/prd, docs/specs, docs/business-rules e lib/api/README.md. `Retry-After` é emitido em exatamente 1 rota: app/api/v1/webhooks/in/[token]/route.ts:62 (`"Retry-After": "60"`); lib/api/client.ts:152 só o LÊ. Bônus: lib/api/README.md:25 aponta para um `rate-limit.ts` que não existe em lib/api/ (o diretório tem client, errors, handlers, recusa, types, wrappers). ``` **Sugestão:** - Rate limit: hoje o produto devolve `Retry-After` em **uma** rota (`app/api/v1/webhooks/in/[token]`) e **nenhum** header `X-RateLimit-*` — a família inteira só existe nos PRDs/specs. Se for implementar, faça no `fail()` de `lib/api/wrappers.ts` para valer em todas as rotas de uma vez; até lá não prometa o header a integrador. Confira: `grep -rin 'x-ratelimit' --include='*.ts' .` **Vira teste:** tests/unit/wrappers.test.ts: afirmar que `fail("rate_limited", …, { status: 429 })` responde com `Retry-After` e `X-RateLimit-Limit`. Nasce vermelho e vira a catraca. ### L61 · FRAGIL · gravidade baixa · sobre-o-codigo > `X-Request-Id` em toda response (correlaciona com audit log) **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && grep -rln 'NextResponse.json' app/api/v1/ && grep -rln 'from "@/lib/api/wrappers"' app/api/v1/ | wc -l && grep -n 'X-Request-Id' lib/api/wrappers.ts ``` **Deu:** ``` lib/api/wrappers.ts seta o header em 3 pontos (linhas 56, 81, 91) — ok()/fail(). 211 arquivos de app/api/v1 importam os wrappers. Mas 3 rotas respondem por fora deles: app/api/v1/health/route.ts, app/api/v1/webhooks/meta/[token]/route.ts, app/api/v1/onboarding/whatsapp/session/route.ts — essas saem sem X-Request-Id. ``` **Sugestão:** - `X-Request-Id` em toda response **que passa por `ok()`/`fail()`** (é o wrapper que o injeta). Três rotas respondem com `NextResponse.json` direto e escapam — `health`, `webhooks/meta/[token]` e `onboarding/whatsapp/session`. Rota nova usa o wrapper; se não usar, não é correlacionável. **Vira teste:** tests/unit/rotas-usam-wrappers.test.ts: varrer app/api/v1/**/route.ts, reprovar `NextResponse.json` fora de uma allowlist nomeada (catraca que só encolhe). ### L76 · FALSA · gravidade media · pendencia > Retenção 5 anos. Hot 90 dias, cold (S3) o resto **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && grep -rin 's3' --include='*.ts' --include='*.sql' lib/ app/api/v1/cron/ supabase/baseline.sql | grep -i 'audit\|cold\|arquiv' && grep -rn 'Retencao 5 anos' supabase/baseline.sql ``` **Deu:** ``` Zero ocorrências de arquivamento em S3 ligado ao audit log. O único vestígio da política é um COMMENT: supabase/baseline.sql:1276 — `COMMENT ON TABLE "public"."api_audit_log" IS 'L-10: Append-only. Retencao 5 anos.'`. Nenhum cron/worker de expurgo ou de cold storage existe (nada em app/api/v1/cron/ toca retenção de audit). ``` **Sugestão:** - Retenção pretendida: 5 anos (registrada como COMMENT em `api_audit_log`). **Nada disso é executado hoje**: não há expurgo de 90 dias nem arquivamento cold em S3 — a tabela só cresce. Tratar como pendência declarada, não como comportamento; quem dimensionar disco de VPS precisa saber disso. ### L92 · FRAGIL · gravidade media · sobre-o-codigo > STOP detection: regex `/STOP|PARAR|SAIR|UNSUBSCRIBE/i` no inbound → `is_blocked=true` automaticamente **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && grep -rn 'UNSUBSCRIBE' --include='*.ts' lib/ app/ workers/ ``` **Deu:** ``` lib/channels/pos-entrada.ts:73 — `export const STOP_RX = /(? pnpm typecheck # tsc --noEmit (estrito) **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && python3 -c "import json;print(json.load(open('package.json'))['scripts']['typecheck'])" && ls tsconfig*.json ``` **Deu:** ``` typecheck = `tsc --noEmit -p tsconfig.typecheck.json`. Existem DOIS tsconfig: tsconfig.json (com `"strict": true`, linha 11) e tsconfig.typecheck.json — o gate roda contra o segundo, não contra o default. ``` **Sugestão:** pnpm typecheck # tsc --noEmit -p tsconfig.typecheck.json (projeto próprio, não o tsconfig.json default) ### L253 · FALSA · gravidade media · contagem > pnpm test:db # Postgres efêmero + baseline install/update + 364 invariantes **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && gh run view --job 94858059457 --log | grep -a 'Test Files\|Tests ' ``` **Deu:** ``` Job `invariants` do run 31828419528 (ci.yml, main, HEAD 840917ed, 2026-08-14T18:26): "Test Files 103 passed (103)" e "Tests 760 passed | 1 expected fail | 1 skipped (762)". Controle local: `ls tests/invariants/*.ts | wc -l` = 107 arquivos. ``` **Sugestão:** pnpm test:db # Postgres efêmero + baseline install/update + a suíte de invariantes (conte: o job `invariants` imprime "Test Files"/"Tests" no fim do log) ### L254 · FALSA · gravidade media · sobre-o-codigo > pnpm test:e2e # Playwright (requer dev server) **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && sed -n '118,140p' playwright.config.ts ``` **Deu:** ``` playwright.config.ts:118-138 — `webServer: { command: \`pnpm exec next start --port ${PORT}\`, …, reuseExistingServer: false }`, com o comentário: "Produção (`next build` antes!): dev-server compila por rota (40-80s) e Turbopack dev quebra cookies() fora do request scope — inviável p/ e2e." Ou seja: a suíte SOBE o próprio servidor de produção e recusa reusar qualquer processo na porta. Contradiz o próprio CLAUDE.md:303, que manda usar `next build` + `next start`. ``` **Sugestão:** pnpm test:e2e # Playwright — exige `pnpm build` antes; ele sobe o próprio `next start` (nunca reusa servidor na porta) ### L261 · FALSA · gravidade alta · ativo-obrigatorio > - **`verify`** (`ci.yml`) — typecheck + lint + test:unit. **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && grep -n ' - name:' .github/workflows/ci.yml ``` **Deu:** ``` verify tem 5 passos executáveis: 'Typecheck' (pnpm typecheck), 'Lint' (pnpm lint), 'Channel provider leak' (pnpm lint:channels, ci.yml:35), 'Unit tests' (pnpm test:unit, ci.yml:38), 'Kit self-host (bash)' (pnpm test:shell, ci.yml:50). A descrição do CLAUDE.md nomeia 3 de 5. ``` **Sugestão:** - **`verify`** (`ci.yml`) — cinco passos, não três: `typecheck`, `lint`, `lint:channels`, `test:unit` e `test:shell` (o kit self-host em bash). Confira a lista na fonte, que é onde ela muda: `grep -n ' - name:' .github/workflows/ci.yml`. **Vira teste:** tests/unit/doutrina-ci.test.ts: ler .github/workflows/ci.yml, extrair os `- name:` do job `verify`, e reprovar quando um passo existir no workflow e não estiver citado no bloco 'Testes' do CLAUDE.md ### L264 · FALSA · gravidade media · contagem > roda **45 das 46 specs** Playwright (medido em 2026-08-14 @ `741c4ec8`; **reconte antes de citar** **Mede com:** ```bash cd "$(git rev-parse --show-toplevel)" && ls tests/e2e/*.spec.ts | wc -l && python3 -c "import yaml;e=yaml.safe_load(open('.github/workflows/e2e.yml'))['jobs']['e2e']['env'];print('RODOU',len(e['SPECS_PARTE_1'].split())+len(e['SPECS_PARTE_2'].split()),'FORA',len(e['FORA_DO_CI'].split()))" ``` **Deu:** ``` 48 specs no disco. SPECS_PARTE_1 = 25, SPECS_PARTE_2 = 22 → RODOU 47; FORA_DO_CI = 1 (vps-fresh-onboarding.spec.ts). Ou seja: 47 de 48, não 45 de 46. Nenhuma spec fora das três listas (a soma fecha). ``` **Sugestão:** - **`e2e`** (`e2e.yml`) — sobe Supabase local, aplica o `baseline.sql` e roda todas as specs de `tests/e2e/` menos as declaradas em `FORA_DO_CI`. **Não cite o número aqui** — ele já apodreceu quatro vezes. Meça: `ls tests/e2e/*.spec.ts | wc -l` para o disco, e o passo "Declarar o que este job ainda NÃO cobre" do próprio job, que CONTA em vez de afirmar. A exclusão de hoje é `vps-fresh-onboarding` (precisa de WAHA + Redis + Resend + Nuvemshop) — e ela é a **P0** da doutrina de QA Visual, ou seja, `e2e` verde **não** prova a jornada de instalação fresca, que é o produto que se vende. **Vira teste:** tests/unit/e2e-cobertura-completa.test.ts já garante a SOMA das três listas. Falta o complemento: reprovar quando o CLAUDE.md contiver a string 'das NN specs' — o número não deve existir na doutrina. ## `CONTRIBUTING.md` — 11 ### L7 · FRAGIL · gravidade media · ponteiro > Identifique o epic de origem em [`docs/stories/epics/MASTER.md`]\(docs/stories/epics/MASTER.md\). **Mede com:** ```bash git log -1 --format='%h %ad %s' --date=short -- docs/stories/epics/ ; git log --since="2026-05-14" --oneline -- docs/stories/epics/ | wc -l ; git log -1 --format=%ad --date=short ``` **Deu:** ``` Último toque: `3eb57cf4 2026-05-06 feat(epic-13): UI Lista agentes + Credentials [wave 10]`. Commits nos últimos 3 meses: **0**. HEAD é de 2026-08-14 — o diretório está parado há 3 meses e 8 dias. O arquivo EXISTE (257 linhas), mas o processo que ele descreve morreu. ``` **Sugestão:** 3. Se a sua mudança nasce de uma issue, cite o número dela no PR. (`docs/stories/epics/` é registro histórico da construção do MVP — último commit em 2026-05-06; não é mais o ponto de partida de contribuição.) **Vira teste:** assertar que CONTRIBUTING.md não manda "identificar o epic de origem" se `git log -1 --format=%ct -- docs/stories/epics/` for mais velho que N dias — ou, mais simples, marcar o diretório como histórico e proibir a instrução ### L22 · FALSA · gravidade media · sobre-o-codigo > Conventional commits + escopo `EPIC-XX` **Mede com:** ```bash git log -60 --format=%s | grep -oE '^[a-z]+\(([^)]+)\)' | sed -E 's/^[a-z]+\(//;s/\)$//' | sort | uniq -c | sort -rn | head -12 ``` **Deu:** ``` 15 marca / 12 onboarding / 3 kit / 2 runbook / 2 ci / 2 auth / 1 vocabulário / 1 u6c / 1 u6b / 1 p4 / 1 merge / 1 J1.21 — **zero** commits com escopo `EPIC-XX` nos últimos 60. ``` **Sugestão:** Conventional commits. O escopo é o **assunto real da mudança** — a área (`marca`, `onboarding`, `kit`, `ci`, `auth`) ou o número da issue (`#184`). Exemplos do que está na `main`: ``` fix(#184): o gate de idempotência deixa de ser decorativo feat(packaging): o worker e o scheduler viram imagem publicada docs(runbook): deploy com os dois arquivos de compose ``` Confira o padrão vigente antes de copiar daqui: `git log -30 --format=%s`. ### L30 · FALSA · gravidade baixa · sobre-o-codigo > O assunto deve ser imperativo e ≤72 chars. **Mede com:** ```bash git log -60 --format=%s | awk 'length($0)>72' | wc -l ``` **Deu:** ``` 35 (de 60 commits, 58% estouram os 72 chars — inclusive os da própria `main` recente) ``` **Sugestão:** Mensagens em PT-BR são aceitas e o assunto deve ser imperativo. **Não há teto de caracteres imposto** — a `main` tem assuntos longos de propósito, porque a frase que explica a mudança vale mais que a coluna 72. Se quiser conferir a prática atual: `git log -30 --format=%s | awk '{print length($0)}' | sort -n | tail -1`. ### L34 · FRAGIL · gravidade media · ponteiro > O `epic-executor` consome o frontmatter (`epic_id`, `priority`, `depends_on`, `status`) e executa wave-by-wave com validação E2E continuous. **Mede com:** ```bash ls .claude/skills/ ; test -e .claude/skills/epic-executor && echo existe || echo AUSENTE_NO_REPO ; grep -rn 'epic_id\|priority\|depends_on' ~/.claude/skills/epic-executor/scripts/*.py | head -5 ``` **Deu:** ``` `.claude/skills/` do repo contém apenas `DeskcommCRM` e `sistema-vivo` → `AUSENTE_NO_REPO`. A skill só existe em `~/.claude/skills/epic-executor/` (instalação pessoal do mantenedor); os campos são de fato lidos lá (`init_epic_state.py:29,54,87,144`). Frontmatter: 15/15 arquivos `EPIC-*.md` têm `epic_id`, `priority`, `depends_on` e `status`. ``` **Sugestão:** Remover a seção `### epic-executor`. Ela descreve uma ferramenta que **não está no repositório** (`.claude/skills/` só traz `DeskcommCRM` e `sistema-vivo`) e um fluxo parado desde 2026-05-06 — quem vem de fora não tem como executá-la e vai gastar tempo procurando. Se ficar, precisa dizer em uma linha: "ferramenta interna do mantenedor, não distribuída no clone". **Vira teste:** para cada ferramenta citada como parte do fluxo em CONTRIBUTING.md, assertar que ela existe no repositório (`.claude/skills/` ou `package.json` scripts) ### L38 · FRAGIL · gravidade baixa · pendencia > Ao finalizar um epic: 1. Atualizar frontmatter `status: pending → completed (partial: ...)` ... 3. Atualizar a row correspondente em `docs/stories/epics/MASTER.md`. **Mede com:** ```bash git log --since="2026-05-14" --oneline -- docs/stories/epics/ | wc -l ``` **Deu:** ``` 0 — nenhum commit atualizou frontmatter ou MASTER.md em 3 meses, apesar de a `main` ter recebido dezenas de features nesse período (packaging, marca própria, onboarding, MFA opcional). ``` **Sugestão:** Remover junto com a seção `### epic-executor` (mesmo processo, mesma morte). Se houver intenção de reviver, o passo é uma issue com dono — não um parágrafo num doc que ninguém executa. ### L50 · FRAGIL · gravidade media · ativo-obrigatorio > **O que o CI reprova sozinho** — rode antes de abrir o PR e não terá surpresa: **Mede com:** ```bash gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(", ")' ; grep -n 'run: pnpm' .github/workflows/ci.yml .github/workflows/perf.yml ``` **Deu:** ``` Obrigatórios: verify, build-and-size, invariants, e2e, imagens-ok. O bloco local cobre `verify` (typecheck, lint, lint:channels, test:unit, test:shell), `build-and-size` (pnpm build) e `invariants` (pnpm test:db) — **3 dos 5**. `e2e` e `imagens-ok` não são exercitados por nenhum comando desse bloco. ``` **Sugestão:** **O que você consegue reproduzir na sua máquina** — cobre 3 dos 5 checks obrigatórios (`verify`, `build-and-size`, `invariants`): ```bash pnpm typecheck && pnpm lint && pnpm lint:channels && pnpm test:unit && pnpm test:shell && pnpm build pnpm test:db # precisa de Docker; sobe um Postgres limpo e aplica o baseline ``` Os outros dois — `e2e` e `imagens-ok` — só rodam no CI e podem te surpreender no PR: o `e2e` sobe Supabase local, e o `imagens-ok` constrói as três imagens Docker (o `next build` de dentro da imagem não enxerga `tests/`, então ele pega coisa que o `pnpm build` daqui não pega). ### L69 · FALSA · gravidade media · ativo-obrigatorio > Nenhum job de CI confere isso **Mede com:** ```bash pnpm vitest run tests/unit/manifest-x-migrations.test.ts 2>&1 | tail -5 ; grep -n 'run: pnpm test:unit' .github/workflows/ci.yml ``` **Deu:** ``` Test Files 1 passed (1) / Tests 6 passed (6) — e `.github/workflows/ci.yml:38: run: pnpm test:unit` dentro do job `verify` (required check). O arquivo guarda os DOIS sentidos: linha do MANIFEST sem arquivo e arquivo sem linha no MANIFEST. ``` **Sugestão:** O CI confere DUAS das três pernas: `tests/unit/manifest-x-migrations.test.ts` (roda no `verify`) reprova migration sem linha no MANIFEST e linha no MANIFEST sem arquivo. A perna que **nenhum job confere** é o baseline: migration sem apêndice em `supabase/baseline.sql` passa verde e simplesmente não chega em quem instalou numa VPS. Confira com `pnpm vitest run tests/unit/manifest-x-migrations.test.ts` **Vira teste:** grep em CONTRIBUTING.md por "Nenhum job de CI confere" cruzado com a existência de tests/unit/manifest-x-migrations.test.ts — se o teste existe, a frase é falsa ### L72 · FALSA · gravidade alta · pendencia > O CI reprova serviço `build:`-only e instalação em tag móvel (imagem quebrada ainda não bloqueia merge) **Mede com:** ```bash gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(", ")' ; sed -n '70,79p' CONTRIBUTING.md ``` **Deu:** ``` verify, build-and-size, invariants, e2e, imagens-ok (e, 5 linhas abaixo, o próprio CONTRIBUTING.md já lista imagens-ok como obrigatório: "Obrigatórios: `verify`, `invariants` (isolamento RLS), `build-and-size`, `e2e` e `imagens-ok`.") ``` **Sugestão:** O CI reprova serviço `build:`-only, instalação em tag móvel e imagem quebrada (`imagens-ok` é required check da `main`); **Vira teste:** o mesmo teste textual do achado da linha 390 — a frase foi replantada no irmão, e o arquivo se contradiz cinco linhas abaixo ### L72 · FALSA · gravidade alta · pendencia > O CI reprova serviço `build:`-only e instalação em tag móvel (imagem quebrada ainda não bloqueia merge) **Mede com:** ```bash gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(", ")' ``` **Deu:** ``` verify, build-and-size, invariants, e2e, imagens-ok ``` **Sugestão:** O CI reprova serviço `build:`-only, instalação em tag móvel **e imagem que não constrói** — as três coisas bloqueiam merge. Confira a lista viva com `gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts'`; **Vira teste:** expect(contexts).toContain('imagens-ok') — assertar que o parêntese "ainda não bloqueia" não sobrevive à ativação do check; ou um teste de doc que proíba a string "ainda não bloqueia merge" em CONTRIBUTING.md enquanto imagens-ok estiver na branch protection ### L82 · FRAGIL · gravidade baixa · ponteiro > O `imagens-ok` (em `.github/workflows/publish-image.yml`) constrói as três imagens que o self-hoster instala **Mede com:** ```bash grep -rn 'imagens-ok' .github/workflows/ ; sed -n '160,180p' .github/workflows/publish-image.yml ; sed -n '58,90p' .github/workflows/publish-image.yml | grep 'name:\|dockerfile:' ``` **Deu:** ``` `.github/workflows/publish-image.yml:160: imagens-ok:` — existe e o path está certo. Mas o job é fachada: `needs: [build-and-push]`, `permissions: {}`, e o único step roda `[ "${{ needs.build-and-push.result }}" = "success" ]`. Quem constrói é `build-and-push`, matriz de 3: deskcommcrm/Dockerfile, deskcomm-worker/Dockerfile.worker, deskcomm-scheduler/Dockerfile.scheduler. ``` **Sugestão:** O `publish-image.yml` constrói as três imagens que o self-hoster instala (`deskcommcrm`, `deskcomm-worker`, `deskcomm-scheduler`); o check `imagens-ok` é o job de fachada que reprova quando qualquer uma delas falha. Roda em PR e **bloqueia** desde 2026-08-13. **Vira teste:** assertar que o job `imagens-ok` existe em .github/workflows/publish-image.yml e que sua lista `needs` cobre o job da matriz de 3 imagens ### L139 · FALSA · gravidade media · ponteiro > Veja [`README.md`]\(README.md\) §Como rodar local. **Mede com:** ```bash grep -n 'Como rodar local' README.md ; grep -n '^#' README.md ``` **Deu:** ``` grep 'Como rodar local' → sem saída (0 ocorrências). Seções reais do README: `## ⚡ Instalar na sua VPS`, `## 🔄 Atualizar`, `## 🧑‍💻 Desenvolvimento (só pra contribuir com o código)` (linha 265), `## 🧪 Testes` (321). ``` **Sugestão:** Veja [`README.md`]\(README.md\) §🧑‍💻 Desenvolvimento — inclui a receita de schema (aplique o `baseline.sql`, **não** as `migrations/`). **Vira teste:** para cada link markdown com âncora `§` num doc, assertar que `` aparece como heading no arquivo apontado ## `README.en.md` — 14 ### L123 · FALSA · gravidade alta · ativo-obrigatorio > have **Google Authenticator** or **Authy** at hand — the first admin login requires MFA **Mede com:** ```bash npx tsx ; grep -n 'mfa_required' scripts/bootstrap-owner.ts ``` **Deu:** ``` dono do install.sh exige MFA? false scripts/bootstrap-owner.ts:215: mfa_required: false, ``` **Sugestão:** (pt-br: mesma correção do README.md, traduzida.) Texto pronto: "Open `https://` (the padlock takes ~1 min to appear) and sign in as the admin. **Two-factor authentication is not required by default** — `install.sh` creates the owner with `mfa_required = false`, on purpose: a full-screen blocker right after onboarding was where fresh installs died. Want to enforce it? Turn it on under **Settings › Security** (the rule lives in `lib/auth/politica-mfa.ts`). During onboarding, scan the QR code with your WhatsApp number." **Vira teste:** o mesmo teste do achado do README.md, varrendo os três arquivos ### L167 · FALSA · gravidade media · data-versao > **The target is the latest published release** (`v1.2.3`), not the tip of `main` **Mede com:** ```bash git tag -l 'v*' --sort=-v:refname | head -1 ; grep -n '1.3.0' CHANGELOG.md ``` **Deu:** ``` v1.3.0 ; CHANGELOG.md:11 "## [1.3.0] — 2026-08-13" ; nenhuma tag nem seção v1.2.3 existe ``` **Sugestão:** (pt-br: apagar o número inventado.) Texto pronto: "**The target is the latest published release** — the newest tag, the same one `git tag -l 'v*' --sort=-v:refname | head -1` returns — not the tip of `main`." ### L174 · FRAGIL · gravidade baixa · sobre-o-codigo > If you see `⚠ avisos que não são os esperados`, that one is worth keeping. **Mede com:** ```bash grep -rn 'avisos que' hostgator-setup-kit/ ; sed -n '144,151p' hostgator-setup-kit/update.sh ``` **Deu:** ``` ZERO ocorrências de 'avisos que'. A string real é update.sh:146 "⚠ Apareceram avisos no banco que NÃO são os esperados:" ``` **Sugestão:** (pt-br: citar a string literal do script.) Texto pronto: "If you see `⚠ Apareceram avisos no banco que NÃO são os esperados:`, that one is worth keeping." ### L234 · FALSA · gravidade media · sobre-o-codigo > | **CRM** | **Kanban** (where each deal sits in the funnel) · **Contacts** · **Pipelines** (stages, business vocabulary and loss reasons) | **Mede com:** ```bash grep -oE 'label: "[^"]+"' lib/navigation/registry.ts ; sed -n '166,210p' lib/navigation/registry.ts ``` **Deu:** ``` grupo crm: "Funis" (/app/kanban), "Contatos", "Etapas do funil" (/app/settings/tenant/pipelines). Comentário no registry: "ERA Kanban ... o produto tinha CINCO vocabulários para a mesma coisa"; e "Pipeline é palavra de quem construiu o sistema; funil de vendas é palavra de quem vende". ``` **Sugestão:** (pt-br: o produto baniu "Kanban"/"Pipeline" da interface; o README ensina o vocabulário errado.) Texto pronto: "| **CRM** | **Funis** / Funnels (your sales funnels — click one to open its board) · **Contacts** · **Etapas do funil** / Funnel stages (each funnel's columns, business vocabulary and loss reasons) |" **Vira teste:** tests/unit/readme-telas.test.ts cobrindo os três arquivos ### L238 · FALSA · gravidade baixa · contagem > | **Organization** | **Team** · **Support distribution** · **Organization** · **LGPD** · **API Tokens** · **Security** ... | **Mede com:** ```bash grep -oE 'label: "[^"]+"' lib/navigation/registry.ts | sed 's/label: //' ``` **Deu:** ``` ... "Equipe" "Distribuição de atendimento" "Organização" "Marca" "Billing" "LGPD" "API Tokens" => a tela "Marca" (/app/settings/marca) falta na tabela ``` **Sugestão:** (pt-br: acrescentar a tela Marca.) Texto pronto: "| **Organization** | **Team** · **Support distribution** · **Organization** · **Marca** (white-label: name, logo and accent of the installation) · **LGPD** · **API Tokens** · **Security** (MFA, recovery codes, sessions) · Profile, Notifications, Billing |" ### L240 · FRAGIL · gravidade baixa · ativo-obrigatorio > Every screen has a door in the navigation — CI fails a screen that exists but can only be reached by typing its URL. **Mede com:** ```bash npx vitest run tests/unit/navegacao-completude.test.ts ; sed -n '19,46p' tests/unit/navegacao-completude.test.ts ``` **Deu:** ``` Tests 6 passed (6). ESCOPO declarado: "só app/app/** ... O admin de plataforma (app/admin/), o onboarding e as páginas públicas têm navegação própria". NAV_ALLOWLIST com 7 rotas isentas. ``` **Sugestão:** (pt-br: declarar o escopo e a allowlist.) Texto pronto: "Every `app/app/**` screen has a door in the navigation — or an entry in the allowlist of `tests/unit/navegacao-completude.test.ts` with a written justification. CI fails a new screen that has neither." ### L308 · FALSA · gravidade alta · ativo-obrigatorio > **Four checks are required** to merge into `main` — all verified in branch protection, not just on paper **Mede com:** ```bash gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(", ")' ``` **Deu:** ``` verify, build-and-size, invariants, e2e, imagens-ok ``` **Sugestão:** (pt-br: trocar o numeral pela régua e acrescentar a linha do `imagens-ok`.) Texto pronto: "**The required checks** to merge into `main` are whatever branch protection says — that is the ruler, not this table: `gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(\", \")'`" + nova linha da tabela: "| `imagens-ok` | fails when any of the three published Docker images (`app`, `worker`, `scheduler`) does not build — job `imagens-ok` in `.github/workflows/publish-image.yml` |" **Vira teste:** tests/unit/readme-checks-obrigatorios.test.ts cobrindo os três arquivos ### L313 · FALSA · gravidade media · contagem > runs **618 invariants across 98 files** **Mede com:** ```bash TEST_DB_CONTAINER=fake npx vitest list --config vitest.db.config.ts | grep -c ' > ' ; ls tests/invariants/*.test.ts | wc -l ``` **Deu:** ``` 761 ; 103 ``` **Sugestão:** (pt-br: trocar o número pelo comando.) Texto pronto: "...and runs the `tests/invariants/**` suite — RBAC, assignment, scoping, routing, follow-up, webhooks and automations. For today's number: `TEST_DB_CONTAINER=x npx vitest list --config vitest.db.config.ts | grep -c ' > '`" ### L315 · FALSA · gravidade media · contagem > runs **44 of the 45** Playwright specs through the frontend **Mede com:** ```bash ls tests/e2e/*.spec.ts | wc -l ; python3 ``` **Deu:** ``` disco: 48 ; rodam 47 (25+22) ; fora 1 (vps-fresh-onboarding) ; nao listadas: [] ``` **Sugestão:** (pt-br: tirar o par de números.) Texto pronto: "| `e2e` | boots a local Supabase, applies `baseline.sql` and runs **every spec in `tests/e2e/` but one** through the frontend — the job itself fails if a spec on disk is in none of the three lists. Recount with `ls tests/e2e/*.spec.ts | wc -l` |" ### L319 · FRAGIL · gravidade baixa · sobre-o-codigo > proves a user of org A sees **zero rows** of org B in `conversations`, `messages`, `contacts` and `crm_leads`. A control case first proves org B's rows actually exist **Mede com:** ```bash sed -n '200,258p' tests/invariants/rls-isolation.test.ts ``` **Deu:** ``` TABLES tem 12 entradas (conversations ... org_guardrail_layers), não 4. O caso "superuser sees both orgs (seed sanity)" roda DEPOIS do laço, não antes. ``` **Sugestão:** (pt-br: 12 tabelas e o controle vem depois.) Texto pronto: "...proves a user of org A sees **zero rows** of org B in every table of the `TABLES` list in `tests/invariants/rls-isolation.test.ts` — 12 today, from `conversations` to `org_guardrail_layers`. Each table carries a positive control (user A still reads their own org's rows), and the suite closes by checking both orgs' rows really exist — without that, the test would pass against an empty table." ### L336 · FALSA · gravidade media · contagem > Index of all 157 documents, with a precedence rule **Mede com:** ```bash git ls-files 'docs/**/*.md' | wc -l ; find docs -name '*.md' | wc -l ; grep -n '149' docs/index.md ``` **Deu:** ``` 151 ; 161 ; docs/index.md:13 "Mapa dos **149** arquivos .md de docs/ ... régua: git ls-files 'docs/**/*.md' | wc -l" ``` **Sugestão:** (pt-br: trocar o total pela régua.) Texto pronto: "| [`docs/index.md`]\(docs/index.md\) | Index of the `docs/` documents, with a precedence rule for when two docs disagree (the index itself carries the ruler: `git ls-files 'docs/**/*.md' | wc -l`) |" ### L361 · FALSA · gravidade alta · ativo-obrigatorio > That line is the **complete** list of required gates on purpose **Mede com:** ```bash gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(", ")' ; sed -n '356,358p' README.en.md ``` **Deu:** ``` protection: verify, build-and-size, invariants, e2e, imagens-ok README.en.md:356: pnpm typecheck && pnpm lint && pnpm lint:channels && pnpm test:unit && pnpm test:shell && pnpm build README.en.md:357: pnpm test:db => cobre verify + build-and-size + invariants; NÃO cobre e2e nem imagens-ok. ``` **Sugestão:** (pt-br: dizer que a linha é só o que roda local.) Texto pronto: "That line is everything you can run on **your own machine**, on purpose: running half of them and discovering the rest as a red surprise after hours of waiting is the worst first experience this repository knows how to deliver. It covers `verify`, `build-and-size` and `invariants`; the other two required checks (`e2e` and `imagens-ok`) only run in CI. The live list comes from `gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(\", \")'`." ### L379 · FRAGIL · gravidade baixa · pendencia > **Foundation & platform** — auth (MFA for admins), multi-tenancy with RLS + isolation test **Mede com:** ```bash npx tsx ; grep -n mfa_required scripts/bootstrap-owner.ts ``` **Deu:** ``` dono do install.sh exige MFA? false ; bootstrap-owner.ts:215 mfa_required: false ``` **Sugestão:** (pt-br: MFA virou opcional.) Texto pronto: "**Foundation & platform** — auth (**optional** two-factor, enforceable per organization or platform-wide under Settings › Security), multi-tenancy with RLS + isolation test, 4-role RBAC, append-only audit log, tenant onboarding." ### L422 · FRAGIL · gravidade media · sobre-o-codigo > **no** performance tracing and **no** session replay, both pinned to 0 on that path **Mede com:** ```bash cat instrumentation-client.ts ``` **Deu:** ``` tracesSampleRate: community ? 0 : 1 ; replaysSessionSampleRate: community ? 0 : 0.1 ; replaysOnErrorSampleRate: 1.0 <-- não depende de `community` ``` **Sugestão:** (pt-br: o replay DE ERRO continua ligado — omitir isso num parágrafo de privacidade é o pior lugar para omitir.) Texto pronto: "— **no** performance tracing and **no** session replay (both pinned to 0 on that path). Error replay stays on, deliberately: it only records when there is an error, it is what explains the stack trace, and it ships with `maskAllText`/`blockAllMedia`." ## `README.es.md` — 14 ### L124 · FALSA · gravidade alta · ativo-obrigatorio > mano **Google Authenticator** o **Authy** — el primer inicio de sesión de admin exige MFA **Mede com:** ```bash npx tsx ; grep -n 'mfa_required' scripts/bootstrap-owner.ts ``` **Deu:** ``` dono do install.sh exige MFA? false scripts/bootstrap-owner.ts:215: mfa_required: false, ``` **Sugestão:** (pt-br: mesma correção do README.md, traduzida.) Texto pronto: "Abre `https://` (el candado tarda ~1 min en aparecer) y entra con el admin. La **verificación en dos pasos no se exige por defecto** — el `install.sh` crea al dueño con `mfa_required = false`, a propósito: un bloqueador de pantalla completa justo después del onboarding era donde moría la instalación nueva. ¿Quieres exigirla? Actívala en **Configuración › Seguridad** (la regla vive en `lib/auth/politica-mfa.ts`). En el onboarding, escanea el código QR con el WhatsApp de tu número." **Vira teste:** o mesmo teste do achado do README.md, varrendo os três arquivos ### L167 · FALSA · gravidade media · data-versao > **El objetivo es la última versión publicada** (`v1.2.3`), no la punta de `main` **Mede com:** ```bash git tag -l 'v*' --sort=-v:refname | head -1 ; grep -n '1.3.0' CHANGELOG.md ``` **Deu:** ``` v1.3.0 ; CHANGELOG.md:11 "## [1.3.0] — 2026-08-13" ; nenhuma tag nem seção v1.2.3 existe ``` **Sugestão:** (pt-br: apagar o número inventado.) Texto pronto: "**El objetivo es la última versión publicada** — la tag más nueva, la misma que devuelve `git tag -l 'v*' --sort=-v:refname | head -1` —, no la punta de `main`." ### L174 · FRAGIL · gravidade baixa · sobre-o-codigo > Si aparece `⚠ avisos que não são os esperados`, ahí sí guarda el mensaje. **Mede com:** ```bash grep -rn 'avisos que' hostgator-setup-kit/ ; sed -n '144,151p' hostgator-setup-kit/update.sh ``` **Deu:** ``` ZERO ocorrências de 'avisos que'. A string real é update.sh:146 "⚠ Apareceram avisos no banco que NÃO são os esperados:" ``` **Sugestão:** (pt-br: citar a string literal do script.) Texto pronto: "Si aparece `⚠ Apareceram avisos no banco que NÃO são os esperados:`, ahí sí guarda el mensaje." ### L235 · FALSA · gravidade media · sobre-o-codigo > | **CRM** | **Kanban** (dónde está cada negocio en el embudo) · **Contactos** · **Embudos** (etapas, vocabulario del negocio y motivos de pérdida) | **Mede com:** ```bash grep -oE 'label: "[^"]+"' lib/navigation/registry.ts ; sed -n '166,210p' lib/navigation/registry.ts ``` **Deu:** ``` grupo crm: "Funis" (/app/kanban), "Contatos", "Etapas do funil" (/app/settings/tenant/pipelines). Comentário: "ERA Kanban ... o nome saiu da interface" ``` **Sugestão:** (pt-br: o produto baniu "Kanban" da interface e separou "Funis" de "Etapas do funil".) Texto pronto: "| **CRM** | **Funis** / Embudos (tus embudos de venta — haz clic en uno para abrir su tablero) · **Contactos** · **Etapas do funil** / Etapas del embudo (las columnas de cada embudo, el vocabulario del negocio y los motivos de pérdida) |" **Vira teste:** tests/unit/readme-telas.test.ts cobrindo os três arquivos ### L239 · FALSA · gravidade baixa · contagem > | **Organización** | **Equipo** · **Distribución de atención** · **Organización** · **LGPD** · **API Tokens** · **Seguridad** ... | **Mede com:** ```bash grep -oE 'label: "[^"]+"' lib/navigation/registry.ts | sed 's/label: //' ``` **Deu:** ``` ... "Equipe" "Distribuição de atendimento" "Organização" "Marca" "Billing" "LGPD" "API Tokens" => a tela "Marca" (/app/settings/marca) falta na tabela ``` **Sugestão:** (pt-br: acrescentar a tela Marca.) Texto pronto: "| **Organización** | **Equipo** · **Distribución de atención** · **Organización** · **Marca** (white-label: nombre, logo y color de la instalación) · **LGPD** · **API Tokens** · **Seguridad** (MFA, códigos de recuperación, sesiones) · Perfil, Notificaciones, Billing |" ### L241 · FRAGIL · gravidade baixa · ativo-obrigatorio > Toda pantalla tiene puerta en la navegación — el CI reprueba una pantalla que existe pero a la que solo se llega escribiendo la URL. **Mede com:** ```bash npx vitest run tests/unit/navegacao-completude.test.ts ; sed -n '19,46p' tests/unit/navegacao-completude.test.ts ``` **Deu:** ``` Tests 6 passed (6). ESCOPO: "só app/app/**"; NAV_ALLOWLIST com 7 rotas isentas. ``` **Sugestão:** (pt-br: declarar o escopo e a allowlist.) Texto pronto: "Toda pantalla de `app/app/**` tiene puerta en la navegación — o una entrada en la allowlist de `tests/unit/navegacao-completude.test.ts` con la justificación escrita. El CI reprueba una pantalla nueva que no tenga ni una cosa ni la otra." ### L309 · FALSA · gravidade alta · ativo-obrigatorio > **Cuatro checks son obligatorios** para mergear en `main` — todos verificados en la branch protection, no solo en el papel **Mede com:** ```bash gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(", ")' ``` **Deu:** ``` verify, build-and-size, invariants, e2e, imagens-ok ``` **Sugestão:** (pt-br: trocar o numeral pela régua e acrescentar a linha do `imagens-ok`.) Texto pronto: "**Los checks obligatorios** para mergear en `main` son los de la branch protection — esa es la regla, no esta tabla: `gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(\", \")'`" + nueva fila: "| `imagens-ok` | reprueba cuando alguna de las tres imágenes Docker publicadas (`app`, `worker`, `scheduler`) no construye — job `imagens-ok` en `.github/workflows/publish-image.yml` |" **Vira teste:** tests/unit/readme-checks-obrigatorios.test.ts cobrindo os três arquivos ### L314 · FALSA · gravidade media · contagem > corre **618 invariantes en 98 archivos** **Mede com:** ```bash TEST_DB_CONTAINER=fake npx vitest list --config vitest.db.config.ts | grep -c ' > ' ; ls tests/invariants/*.test.ts | wc -l ``` **Deu:** ``` 761 ; 103 ``` **Sugestão:** (pt-br: trocar o número pelo comando.) Texto pronto: "...y corre la suite de `tests/invariants/**` — RBAC, asignación, alcance, enrutamiento, follow-up, webhooks y automatizaciones. Para el número del día: `TEST_DB_CONTAINER=x npx vitest list --config vitest.db.config.ts | grep -c ' > '`" ### L316 · FALSA · gravidade media · contagem > corre **44 de las 45** specs de Playwright por el frontend **Mede com:** ```bash ls tests/e2e/*.spec.ts | wc -l ; python3 ``` **Deu:** ``` disco: 48 ; rodam 47 (25+22) ; fora 1 (vps-fresh-onboarding) ; nao listadas: [] ``` **Sugestão:** (pt-br: tirar o par de números.) Texto pronto: "| `e2e` | levanta un Supabase local, aplica `baseline.sql` y corre **todas las specs de `tests/e2e/` menos una** por el frontend — el propio job reprueba si una spec del disco no está en ninguna de las tres listas. Recuenta con `ls tests/e2e/*.spec.ts | wc -l` |" ### L320 · FRAGIL · gravidade baixa · sobre-o-codigo > prueba que un usuario de la org A ve **cero filas** de la org B en `conversations`, `messages`, `contacts` y `crm_leads`. Antes, un caso de control prueba que las filas de la org B realmente existen **Mede com:** ```bash sed -n '200,258p' tests/invariants/rls-isolation.test.ts ``` **Deu:** ``` TABLES tem 12 entradas (conversations ... org_guardrail_layers), não 4. O caso "superuser sees both orgs (seed sanity)" roda DEPOIS do laço, não antes. ``` **Sugestão:** (pt-br: 12 tabelas e o controle vem depois.) Texto pronto: "...prueba que un usuario de la org A ve **cero filas** de la org B en cada tabla de la lista `TABLES` de `tests/invariants/rls-isolation.test.ts` — hoy 12, de `conversations` a `org_guardrail_layers`. Cada tabla lleva su control positivo (el usuario A sigue leyendo las filas de su propia org), y la suite cierra comprobando que las filas de ambas orgs realmente existen — sin eso, el test pasaría con la tabla vacía." ### L337 · FALSA · gravidade media · contagem > Índice de los 157 documentos, con regla de precedencia **Mede com:** ```bash git ls-files 'docs/**/*.md' | wc -l ; find docs -name '*.md' | wc -l ; grep -n '149' docs/index.md ``` **Deu:** ``` 151 ; 161 ; docs/index.md:13 "Mapa dos **149** arquivos .md de docs/ ... régua: git ls-files 'docs/**/*.md' | wc -l" ``` **Sugestão:** (pt-br: trocar o total pela régua.) Texto pronto: "| [`docs/index.md`]\(docs/index.md\) | Índice de los documentos de `docs/`, con regla de precedencia cuando dos docs discrepan (el propio índice trae la regla: `git ls-files 'docs/**/*.md' | wc -l`) |" ### L362 · FALSA · gravidade alta · ativo-obrigatorio > Esa línea es la lista **completa** de los gates obligatorios, a propósito **Mede com:** ```bash gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(", ")' ; sed -n '357,358p' README.es.md ``` **Deu:** ``` protection: verify, build-and-size, invariants, e2e, imagens-ok README.es.md:357: pnpm typecheck && pnpm lint && pnpm lint:channels && pnpm test:unit && pnpm test:shell && pnpm build README.es.md:358: pnpm test:db => cobre verify + build-and-size + invariants; NÃO cobre e2e nem imagens-ok. ``` **Sugestão:** (pt-br: dizer que a linha é só o que roda local.) Texto pronto: "Esa línea es todo lo que puedes correr en **tu propia máquina**, a propósito: correr solo la mitad y descubrir el resto como sorpresa roja después de horas de espera es la peor primera experiencia que este repositorio sabe entregar. Cubre `verify`, `build-and-size` e `invariants`; los otros dos checks obligatorios (`e2e` e `imagens-ok`) solo corren en el CI. La lista viva sale de `gh api repos/melgarafael/DeskcommCRM/branches/main/protection --jq '.required_status_checks.contexts|join(\", \")'`." ### L380 · FRAGIL · gravidade baixa · pendencia > **Fundación y plataforma** — auth (MFA para admin), multi-tenancy con RLS + test de aislamiento **Mede com:** ```bash npx tsx ; grep -n mfa_required scripts/bootstrap-owner.ts ``` **Deu:** ``` dono do install.sh exige MFA? false ; bootstrap-owner.ts:215 mfa_required: false ``` **Sugestão:** (pt-br: MFA virou opcional.) Texto pronto: "**Fundación y plataforma** — auth (verificación en dos pasos **opcional**, exigible por organización o por la plataforma en Configuración › Seguridad), multi-tenancy con RLS + test de aislamiento, RBAC de 4 roles, audit log append-only, onboarding de tenant." ### L423 · FRAGIL · gravidade media · sobre-o-codigo > **sin** rastreo de performance y **sin** replay de sesión, que quedan en 0 en ese camino **Mede com:** ```bash cat instrumentation-client.ts ``` **Deu:** ``` tracesSampleRate: community ? 0 : 1 ; replaysSessionSampleRate: community ? 0 : 0.1 ; replaysOnErrorSampleRate: 1.0 <-- não depende de `community` ``` **Sugestão:** (pt-br: o replay DE ERRO continua ligado.) Texto pronto: "— **sin** rastreo de performance y **sin** replay de sesión (los dos en 0 en ese camino). El replay **de error** sigue activo, a propósito: solo graba cuando hay un error, es lo que explica el stack trace, y ya sube con `maskAllText`/`blockAllMedia`." ## `README.md` — 15 ### L121 · FALSA · gravidade alta · ativo-obrigatorio > o primeiro login de admin exige MFA **Mede com:** ```bash cat lib/auth/politica-mfa.ts; sed -n '195,225p' scripts/bootstrap-owner.ts; npx tsx