feat(squads): bounded contexts + ADRs for onboarding & squads governance by danielhe4rt · Pull Request #332 · he4rt/heartdevs.com

danielhe4rt · 2026-06-16T03:26:46Z

O quê

Estabelece dois novos bounded contexts — onboarding (camada de Entrada) e squads (Governança) — via scaffold dos módulos + documentação de domínio (CONTEXT.md + ADRs). Sem código de runtime ainda — é a fundação de design que destrava a implementação.

Resultado de uma sessão /grill-with-docs sobre o Mapa de Fluxos dos Squads (camadas Entrada + Governança; o Núcleo do jogo fica de fora por enquanto).

Decisões principais (ver ADRs)

Onboarding (Entrada)

ADR-0001 — Onboarding polimórfico por tipo (OnboardingType → handler(), mesmo idioma do IdentityProvider::getClient). Modelo onboarding + tabela onboarding_steps (auditoria por etapa). Cadeia de pré-requisitos entre tipos (Welcome é pré-req de Squads). "APTO" = Squads onboarding concluído.
ADR-0002 — Sinal de "PR aprovado" via novo evento de domínio GithubPullRequestApproved do integration-github (transporte continua centralizado; HMAC/dedup reusados). Repo de desafio via GithubRepository.purpose = challenge. Vínculo do GitHub é gate → sem reconciliação (diverge do BDD original da P.O.).

Squads (Governança)

ADR-0001 — Governança como record-keeping, não workflow engine. Eleição/remoção/saída/realocação rodam off-system; o módulo registra o resultado. Candidatura é o único fluxo conduzido. Autoridade = super-admins (config('he4rt.admins')) + capitão gere o próprio squad.
ADR-0002 — Modelo de dados: squads, squad_members (pivot com role), squad_membership_events (append-only), squad_applications. Capitão derivado do pivot (sem captain_id). Capitão único + exclusividade "1 squad ativo" garantidos no banco (partial unique) + validação na Action.

Fora de escopo (regras humanas, aplicadas off-system)

Elegibilidade "≥1 entrega", desempate pelo Head, candidatura única, mínimo de votos proporcional, "sem reeleição direta". Só o resultado é registrado — por isso o ponto aberto "definição de entrega" não bloqueia.

Arquivos

CONTEXT-MAP.md — registra os dois contextos + regras de dependência
app-modules/onboarding/ — scaffold + CONTEXT.md + 2 ADRs
app-modules/squads/ — scaffold + CONTEXT.md + 2 ADRs

Follow-ups (não neste PR)

Implementação: migrations, models (com PHPDoc), enums, Actions, Policy, listener do GithubPullRequestApproved, campo GithubRepository.purpose
Mover *ServiceProvider de src/Providers/ → src/ (guideline .ai/02-module-architecture)
Atualizar o documento da P.O. (cenário de reconciliação removido)

…vent

stherzada

Avalie as considerações, e me dê um toque.

stherzada · 2026-06-16T23:38:39Z

+1. **Onde mora?** A pré-triagem é sobre pertencer à comunidade, não a um squad específico, e reusa
+   pesado o `identity` (vínculo GitHub via `ExternalIdentity`). Colocá-la dentro de `squads`
+   amarraria um conceito universal a um consumidor específico.


Suggested change

1. **Onde mora?** A pré-triagem é sobre pertencer à comunidade, não a um squad específico, e reusa

pesado o `identity` (vínculo GitHub via `ExternalIdentity`). Colocá-la dentro de `squads`

amarraria um conceito universal a um consumidor específico.

1. **Esse onboarding é específico de um squad ou global da comunidade?** A pré-triagem é sobre pertencer à comunidade, não a um squad específico, e reusa

pesado o `identity` (vínculo GitHub via `ExternalIdentity`). Colocá-la dentro de `squads`

amarraria um conceito universal a um consumidor específico.

Recomendo trocar a pergunta, pois confesso que após a leitura fiquei confusa sobre o que se tratava.

stherzada · 2026-06-16T23:39:30Z

+- **STI / modelo por tipo**: Laravel não tem STI nativo (exige pacote/boilerplate), foge do idioma
+  `enum→resolve` do repo e incha o schema com colunas nuláveis por tipo. Descartado.


Suggested change

- **STI / modelo por tipo**: Laravel não tem STI nativo (exige pacote/boilerplate), foge do idioma

`enum→resolve` do repo e incha o schema com colunas nuláveis por tipo. Descartado.

Se foi descartado não faz sentido ter dentro desse contexto.

stherzada · 2026-06-16T23:42:22Z

+2. Como distinguir um "repo de desafio" de um repo de contribuições — sem que o `git_challenge` vire
+   XP de gamification.


Nesse caso aqui acho que pode ser validado até por nome mesmo, ele não precisa entrar muito afundo nessa lógica pois acredito que até o momento não visamos tantos repos desafios por hora.

stherzada · 2026-06-16T23:43:46Z

+  acoplamento mínimo e consciente, mitigado por ser categoria de projeção, não lógica de onboarding.
+- O repo de desafio precisa ter o webhook do GitHub instalado apontando pro endpoint do
+  `integration-github` (setup de infra, não de código).
+- Diverge do BDD original (reconciliação removida) — o documento da P.O. precisa ser atualizado.


Gera essa doc que foi citada aqui, por favor

stherzada · 2026-06-16T23:45:19Z

Trago o questionamento, acha válido deixar o context.md em inglês?
Pois seguindo essa lógica acho justo seguir todo processo em apenas uma língua, mas vale saber se isso pode ser uma limitação no futuro.

stherzada · 2026-06-16T23:47:30Z

+| Term               | Definition                                                                                                                                                                      | Not to be confused with                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| **Onboarding**     | One person's journey through one typed flow, scoped to a tenant. One row per `(tenant, user, type)`. Holds lifecycle `status`, not the per-step detail.                         | The UI wizard (presentation) — the Onboarding is the persisted state machine   |
+| **OnboardingType** | The discriminator enum (`Welcome`, `Squads`, …). Resolves the polymorphic behaviour via `handler(): OnboardingFlow` — same idiom as `IdentityProvider::getClient`.              | A step — a type _has_ steps                                                    |


Fiquei curiosa, qual diferença dessa para o OnboardingStep?

stherzada · 2026-06-17T00:03:35Z

+  a condução. Risco de o estado lançado divergir do que aconteceu de fato (mitigado pela trilha + por
+  o lançamento ser feito por super-admin/capitão).
+- Regras como "sem reeleição direta" não são impedidas pelo sistema — dependem de disciplina humana.
+- Vários cenários BDD do documento da P.O. não viram testes de software nesta fase.


Qual nesse caso, se poder gerar esse cenários, ficaria grata

stherzada · 2026-06-17T00:04:28Z

No geral não entendi quais decisões ele viu de problema, necessito de mais contexto para atuar nesse review.

stherzada · 2026-06-17T00:06:14Z

Trago o questionamento, acha válido deixar o context.md em inglês?
Pois seguindo essa lógica acho justo seguir todo processo em apenas uma língua, mas vale saber se isso pode ser uma limitação no futuro.

Clintonrocha98 · 2026-06-19T16:53:30Z

up!

danielhe4rt added 10 commits June 15, 2026 23:52

chore(squads): scaffold module structure

7af50a0

chore(onboarding): scaffold module structure

30712e2

chore(deps): register onboarding and squads modules

1d669b6

docs(onboarding): add bounded-context glossary

c9e3168

docs(onboarding): add ADR-0001 polymorphic onboarding by type

e784d19

docs(onboarding): add ADR-0002 PR-approval signal via github domain e…

33fbfa4

…vent

docs(squads): add bounded-context glossary

e696486

docs(squads): add ADR-0001 governance as record-keeping

0cb4fc3

docs(squads): add ADR-0002 squads data model

9114069

docs(architecture): map onboarding and squads contexts

dd2a5d5

github-actions Bot assigned danielhe4rt Jun 16, 2026

stherzada suggested changes Jun 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(squads): bounded contexts + ADRs for onboarding & squads governance#332

feat(squads): bounded contexts + ADRs for onboarding & squads governance#332
danielhe4rt wants to merge 10 commits into
4.xfrom
feat/onboarding-squads

danielhe4rt commented Jun 16, 2026

Uh oh!

stherzada left a comment

Uh oh!

stherzada Jun 16, 2026

Uh oh!

stherzada Jun 16, 2026

Uh oh!

stherzada Jun 16, 2026

Uh oh!

stherzada Jun 16, 2026 •

edited

Loading

Uh oh!

stherzada Jun 16, 2026

Uh oh!

stherzada Jun 16, 2026

Uh oh!

stherzada Jun 17, 2026 •

edited

Loading

Uh oh!

stherzada Jun 17, 2026

Uh oh!

stherzada Jun 17, 2026

Uh oh!

Clintonrocha98 commented Jun 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		- STI / modelo por tipo: Laravel não tem STI nativo (exige pacote/boilerplate), foge do idioma
		`enum→resolve` do repo e incha o schema com colunas nuláveis por tipo. Descartado.

		2. Como distinguir um "repo de desafio" de um repo de contribuições — sem que o `git_challenge` vire
		XP de gamification.

Conversation

danielhe4rt commented Jun 16, 2026

O quê

Decisões principais (ver ADRs)

Fora de escopo (regras humanas, aplicadas off-system)

Arquivos

Follow-ups (não neste PR)

Uh oh!

stherzada left a comment

Choose a reason for hiding this comment

Uh oh!

stherzada Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

stherzada Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

stherzada Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

stherzada Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stherzada Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

stherzada Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

stherzada Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stherzada Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

stherzada Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

Clintonrocha98 commented Jun 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stherzada Jun 16, 2026 •

edited

Loading

stherzada Jun 17, 2026 •

edited

Loading