Deskcomm Contribuir

Contribuir para o DeskcommCRM sem retrabalho

Quem contribui aqui quase nunca erra por falta de capacidade — erra por não saber a régua. A régua existe, mas está espalhada em três documentos (CLAUDE.md, CONTRIBUTING.md e o procedimento de triagem, com mais de 100 KB) e é aplicada depois do PR, por quem mantém. Este guia aplica a mesma régua antes, do seu lado, para o PR chegar pronto. Taxa histórica de recusa de PR de fork: zero. O que trava é retrabalho — e retrabalho se evita medindo.

Como você age

• Aconselha, não bloqueia. Você mede e mostra; só os hooks de git bloqueiam, e só o que é irreversível (push na main, migration sem a tripla). Uma pessoa que quer seguir mesmo assim segue — sabendo o que vai acontecer na triagem.
• Mede na fonte, nunca copia número. A lista de checks obrigatórios, quantas specs rodam e o que o CI cobre mudam toda semana; cada afirmação vem com o comando que a produziu.
• Declara o que não mediu. Um PR que diz "não rodei o e2e porque não tenho Docker" é melhor que um que marca tudo. O mantenedor prova o que ficou faltando; a régua pública é essa.
• Sabota antes de dizer "testado". Teste que não fica vermelho quando o conserto sai não guarda nada.

Passo 0 — quem está contribuindo

Este passo vem antes de trazer a main (Passo 1), então não conte com o script estar no clone: um fork anterior a 2026-09-10 ainda não o tem, e o guia pode ter vindo da instalação global. O comando abaixo procura o script na raiz do clone (vale de qualquer subpasta dele) e, se não achar, nas três pastas globais em que o instalar-guias.sh põe os guias. Cole como está, de onde você estiver:

r="$(git rev-parse --show-toplevel 2>/dev/null)"; s=""
for g in ${r:+"$r/.agents/skills"} ~/.claude/skills ~/.agents/skills ~/.gemini/config/skills; do
  [ -f "$g/deskcomm-contribuir/scripts/quem-sou.sh" ] && { s="$g/deskcomm-contribuir/scripts/quem-sou.sh"; break; }
done
if [ -n "$s" ]; then bash "$s"; else
  echo "NÃO MEDIDO — não achei o quem-sou.sh ${r:+no clone $r }nem nas pastas globais dos guias." >&2
  echo "Instale os guias pelo comando de uma linha do README (https://github.com/melgarafael/DeskcommCRM#readme) e rode de novo." >&2
  false
fi

A resposta vem da pasta onde você rodou, não de onde o script mora: fora de um clone ela é contribuidor — fora de um clone git, e se afina sozinha assim que o terminal estiver dentro do clone.

A resposta decide o resto do guia, e são três:

• Começa com mantenedor: este guia fica quieto — o mantenedor tem o próprio ritual (triagem, gov-loop) e hooks próprios em loop/hooks. Só siga se a pessoa pedir por nome.
• Começa com contribuidor: siga. O script diz por quê (e-mail do git no .mailmap, conta do gh, o origin ser fork).
• Começa com NÃO MEDIDO (e o bloco sai com erro): o script não está nem no clone nem nas pastas globais — um fork anterior a 2026-09-10 sem a instalação global, ou um terminal fora de clone sem ela. Ninguém foi classificado: não trate a pessoa como mantenedor nem como contribuidor por essa saída. Instale os guias pelo comando de uma linha do README, que a própria saída aponta, e rode este passo de novo — vale de qualquer pasta, inclusive num fork cujo main ainda não tem o script.

Passo 1 — a âncora: origin/main, nunca o disco

git fetch origin
MAIN=$(git rev-parse --short origin/main); echo "main=$MAIN"
B=$(git merge-base origin/main HEAD)
echo "atraso=$(git rev-list --count $B..origin/main) proprios=$(git rev-list --count $B..HEAD)"
comm -12 <(git diff --name-only $B origin/main | sort) <(git diff --name-only $B HEAD | sort)   # sobreposição

• Branch nova nasce de origin/main deste repositório, com nome (fix/o-que-conserta), nunca do main do fork: o main do fork carrega as personalizações da instalação da pessoa (marca, .env, config) e um PR aberto dali propõe tudo isso ao produto inteiro — foi medido, sete arquivos com a marca de um cliente mergeando sem conflito (PR #465).
• Atraso > 0 → traga a main para dentro: git merge --ff-only origin/main se proprios=0, senão git merge origin/main. Nunca reset --hard nem push --force: apaga trabalho. Conflito se resolve lendo os dois lados (ver references/pre-voo.md, seção "conflito").
• Sobreposição (arquivos que a main também mudou) é onde nasce conflito: mescle cedo, não na hora do PR.
• O CI testa a branch, não o resultado do merge (strict=false na proteção da main): verde na branch atrasada não prova nada sobre o merge.

Passo 2 — arme os hooks (uma vez por clone)

bash .agents/skills/deskcomm-contribuir/scripts/armar-hooks.sh

Três guardas, e só isso: pre-commit reprova migration nova sem apêndice no baseline.sql e sem linha -- manifest: <descrição> no cabeçalho do .sql no mesmo commit, e número (NNNN) ou timestamp já usado na população da pergunta — a main do PRODUTO (o remoto que aponta para melgarafael/DeskcommCRM, com qualquer nome; num fork, a sua origin/main é a main do fork e não vale) mais refs/heads e refs/remotes. O que essa população não cobre são os PRs abertos, e a mensagem do hook diz isso e aponta pnpm checar:colisao-de-migration, que mede também eles. O NNNN sai da posição do nome canônico (^[0-9]{14}_([0-9]{4})_), e a regra está em migration-populacao.sh, na pasta scripts/ da raiz do repositório (issue #1273); pre-push reprova push na main; e os dois avisam (sem bloquear) quando o commit está assinado como root@… ou sem e-mail — trabalho assinado assim não aparece no perfil do GitHub de quem fez. O mantenedor roda hooks próprios (loop/hooks); o script recusa sobrescrevê-los.

Passo 3 — antes de codar

• Leia a doutrina do que vai tocar: a skill deskcomm-doutrina aponta as três regras que mais custam (multi-tenancy com RLS, tripla de migration, nenhuma feature nomeia provider) e manda abrir o CLAUDE.md da origin/main — não de um resumo.
• Issue: comente "pego esta" antes de codar; um mantenedor atribui. Sem resposta em 48 h, comece e diga no PR. Issue com pessoa atribuída não se duplica.
• Peça de sistema (lead, agente, follow-up, tela, worker, métrica)? Carregue a skill sistema-vivo — o Living System Checklist é item do Definition of Done.

Passo 4 — o pré-voo, antes de abrir o PR

bash .agents/skills/deskcomm-contribuir/scripts/pre-voo.sh

Ele imprime, medido e com o comando ao lado, o que o mantenedor vai medir: atraso e sobreposição, arquivos fora do produto no diff (marca, .env, config do fork), segredo no diff, console.log novo (o lint só avisa), migration nova e a tripla, seção de versão escrita à mão no CHANGELOG.md (bloqueador — o corte de release é automático), fragmento em .changes/, documento de autoridade tocado, identidade dos commits. A leitura de cada item e o que fazer: references/pre-voo.md.

Depois, os gates que o CI roda sozinho — rode a suíte, não os gates que você lembra:

rm -f tsconfig*.tsbuildinfo; pnpm typecheck; echo exit=$?
pnpm lint; echo exit=$?
pnpm lint:channels; echo exit=$?
pnpm test:unit > /tmp/vt.log 2>&1; echo exit=$?; grep -aE "Test Files|Tests " /tmp/vt.log | tail -2
pnpm test:shell; echo exit=$?          # se tocou hostgator-setup-kit/, Dockerfile* ou compose
pnpm test:db; echo exit=$?             # se tocou schema/RLS/RBAC (precisa de Docker)
pnpm build; echo exit=$?

test:unit sem caminho: o script alcança o repositório inteiro (testes ao lado do código inclusive); vitest run tests/unit é um verde menor. Não corte a saída com tail — o rodapé é a autoridade e os nomes dos arquivos vermelhos são o único dado que permite reconciliar.

Passo 5 — o teste que falta, e a sabotagem

Mudou comportamento? Então existe um teste que fica vermelho sem a sua mudança. Se não existe, escreva. Depois commite e sabote: reverta só a linha do conserto (não o commit), preveja quantos casos vão cair (e quais), rode, confira a contagem, restaure. "1 vermelho de N, o previsto" vai no corpo do PR. Sabotar antes de commitar já custou trabalho perdido aqui mais de uma vez.