feat(project): auto-add issues + reconcile workflows para nfe/5

[joaokita]

Contexto

Issues criadas pela UI do GitHub hoje não entram automaticamente no Project Work - Product & Engineering (nfe/5) — só issues criadas via skill /create-issue (que faz addProjectV2ItemById explicitamente). Isso gera issues órfãs, que ficam rastreadas no repo mas fora do Project central.

Required Workflows (feature original de 2023) foi descontinuada. Rulesets (seu sucessor) só cobre eventos de PR/push — não cobre issues.opened. Logo, não há mecanismo GitHub nativo que force um workflow a rodar org-wide no evento de issue. A solução é sincronizar o workflow pra cada repo + reconciler como safety-net.

O que este PR adiciona

Três arquivos, nenhuma mudança em código existente:

1. templates/auto-add-to-project.yml (template de sync)

Workflow que será copiado pra cada repo. Dispara em issues: [opened, reopened, transferred] e usa actions/add-to-project@v1 pra adicionar a issue ao Project #5. Delay típico <30s.

2. .github/workflows/sync-auto-add-workflow.yml (provisioner)

Roda diariamente 06:00 UTC + manual via workflow_dispatch. Pra cada repo não-arquivado da org:

• Se o arquivo já existe e está idêntico ao template → pula
• Se PR de sync já está aberto → pula
• Senão → cria branch chore/auto-add-to-project-sync, commita o template, abre PR contra main/default branch do repo

Inputs do dispatch manual:

• dry_run (default false): lista o que faria sem abrir PR
• limit (default 0): max repos a processar por execução (0 = todos)

3. .github/workflows/reconcile-project-items.yml (reconciler)

Roda a cada hora + manual. Encontra issues abertas na org ausentes do Project #5 e adiciona. Safety-net pra: (a) repos ainda sem workflow syncado, (b) falhas transitórias do workflow primary, (c) issues transferidas / reabertas fora de evento.

Apenas adiciona ao Project — não seta fields (Priority, Status, etc. ficam vazios, pra preenchimento manual/Triage).

Arquitetura

┌─ PRIMARY (<30s) ─────────────────────────────┐
│ issues.opened em qualquer repo com o workflow│
│ → actions/add-to-project@v1 → Project #5     │
└──────────────────────────────────────────────┘
┌─ PROVISIONER (daily) ────────────────────────┐
│ nfe/.github → sync-auto-add-workflow         │
│ → abre PR em cada repo sem o workflow        │
│   (aprovação manual por você)                │
└──────────────────────────────────────────────┘
┌─ RECONCILER (hourly) ────────────────────────┐
│ nfe/.github → reconcile-project-items        │
│ → diff (issues abertas - issues no Project)  │
│ → addProjectV2ItemById em cada orfã          │
└──────────────────────────────────────────────┘

⚠️ Pré-requisito manual (antes de merge)

Criar e expor secret organization-level WORK_PROJECT_TOKEN:

1. Criar PAT em https://github.com/settings/tokens com scopes:

   • repo — pra commit e abrir PR nos repos alvo (provisioner)
   • workflow — pra commitar arquivos em .github/workflows/ (provisioner)
   • project — pra addProjectV2ItemById (runtime e reconciler)

2. Adicionar como secret org-level em https://github.com/organizations/nfe/settings/secrets/actions:

   • Name: WORK_PROJECT_TOKEN
   • Value: (o PAT criado)
   • Repository access: "All repositories" (ou seleção que inclua todos os repos alvo + nfe/.github)

Sem esse secret, o workflow actions/add-to-project@v1 falha silenciosamente e os PRs do provisioner não abrem.

Plano de rollout recomendado

1. Merge este PR após revisar os 3 arquivos
2. Configurar o secret conforme acima
3. Rodar provisioner em dry-run via Actions → Sync auto-add-to-project workflow → Run workflow → dry_run=true — valida a lista de repos sem efeito colateral
4. Rodar provisioner limitado via limit=3, dry_run=false — valida o fluxo de PR em 3 repos
5. Aprovar esses PRs manualmente (você pediu aprovação manual)
6. Liberar cron normal (daily 06:00 UTC) — nos próximos ciclos, os demais repos recebem PRs
7. Rodar reconciler manualmente em dry-run uma vez — confirma o número de órfãs esperadas
8. Liberar cron do reconciler (1h) — cadence normal

Notas operacionais

• Não ignora nenhum repo (forks e private inclusos) — como você pediu. Repos arquivados são pulados pois não aceitam commit.
• Primeiro disparo do reconciler vai adicionar todas as issues abertas na org que ainda não estão no Project feat(skills): adicionar skill create-issue com Origem e Referências obrigatórias #5. Pode ser volumoso no primeiro ciclo.
• Idempotência: ambos os workflows são idempotentes — rodar 2× não duplica (provisioner compara conteúdo, reconciler usa set diff).
• Poluição por repo: cada repo ficará com 1 arquivo .github/workflows/auto-add-to-project.yml. É o trade-off da Arquitetura B (sem Workers hospedado).

Test plan

• Secret WORK_PROJECT_TOKEN criado e visível org-wide
• Provisioner executado em dry_run=true — lista de repos confere com gh api orgs/nfe/repos
• Provisioner executado com limit=3 — 3 PRs abertos corretamente em 3 repos
• Merge de 1 PR piloto → nova issue naquele repo entra no Project em <1min
• Reconciler executado em dry_run=true — contagem de órfãs bate com query manual
• Reconciler executado normal — órfãs adicionadas, sem duplicar no próximo ciclo

🤖 Generated with Claude Code