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-17T00:04:28Z

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

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

up!

stherzada · 2026-06-21T17:58:43Z

up!

Co-authored-by: Sther <72408918+stherzada@users.noreply.github.com> Signed-off-by: Daniel Reis <danielhe4rt@gmail.com>

stherzada · 2026-06-21T19:00:00Z

Comentário do Elves:

Tenho apenas duas observações:

No squad_members com role no pivot, o papel de capitão está garantido pela partial unique constraint, o que faz sentido. Talvez valha considerar também a geração de um evento em squad_membership_events quando houver troca de capitão, para manter a trilha de auditoria consistente com o restante do modelo.

O GithubPullRequestApproved, que vem do módulo de integração com o GitHub, será disparado por webhook ou por polling?

danielhe4rt · 2026-06-21T19:01:59Z

No squad_members com role no pivot, o papel de capitão está garantido pela partial unique constraint, o que faz sentido. Talvez valha considerar também a geração de um evento em squad_membership_events quando houver troca de capitão, para manter a trilha de auditoria consistente com o restante do modelo.

R: Faz sentido capturar qualquer evento de uma squad. Por mais simples que seja, é o que precisamos no momento.

O GithubPullRequestApproved, que vem do módulo de integração com o GitHub, será disparado por webhook ou por polling?

R: Ambos serão o mesmo payload, no final, o meio não importa desde que tenha a Action fazendo essa fronteira entre o Transporter;

stherzada

Só não esquece de mandar o a doc lá!

gvieira18 · 2026-06-22T03:35:22Z

Pendente composer update para ajustar o composer.lock

> composer install Installing dependencies from lock file (including require-dev) Verifying lock file contents can be installed on current platform. Warning: The lock file is not up to date with the latest changes in composer.json. You may be getting outdated dependencies. It is recommended that you run `composer update` or `composer update <package name>`. - Required package "he4rt/onboarding" is not present in the lock file. - Required package "he4rt/squads" is not present in the lock file. This usually happens when composer files are incorrectly merged or the composer.json file is manually edited. Read more about correctly resolving merge conflicts https://getcomposer.org/doc/articles/resolving-merge-conflicts.md and prefer using the "require" command over editing the composer.json file directly https://getcomposer.org/doc/03-cli.md#require-r

guisaliba · 2026-06-24T03:30:25Z

+| `completed_at`  | timestamptz?                |                                                   |
+| timestamps      | tz                          |                                                   |
+| UNIQUE          | `(onboarding_id, step_key)` |                                                   |
+


pra fins de auditoria de transicionamento e checks mais rapidos, nao valeria armazenar a transição de steps com uma coluna de previously_at? traria ganho pra disciplina de transition mencionada na linha 102

ou eles foram desenhados pra serem "ever-forward" (flow nao é um grafo direcionado, apenas guarda estados)?

guisaliba · 2026-06-24T03:41:11Z

+PR do candidato** num repo de desafio. A plataforma precisa reagir a essa aprovação.
+
+O `integration-github` já é o **único** ponto que fala com o GitHub: `GithubWebhookController` recebe
+todos os webhooks, grava no `GithubEventLog` (lake, dedup por `delivery_id`), e o `ProjectGithubEvent`


estamos distinguindo repositório de projeto ou ambas palavras se referem à mesma coisa? um evento emitido por um repositorio deveria RepoGithubEvent ou ProjectGithubEvent como é agora?

guisaliba · 2026-06-24T03:58:23Z

por que os CONTEXT.md estão em inglês e os ADRs não? pra fins de linguagem ubiqua, não deveria serem todos no mesmo idioma?

guisaliba · 2026-06-24T04:00:19Z

+  consulta interna do `integration-github`) e furaria o encapsulamento do lake. Descartado.
+- **Config de repo de desafio dentro do `onboarding`** (em vez do `purpose` na allowlist): manteria o
+  `integration-github` sem nenhuma categoria nova, mas duplicaria o cadastro de repos e perderia o
+  benefício de excluir o repo de desafio da projeção de contribuições num lugar só. Trade-off aceito


com o purpose acoplamos a entidade do GithubRepository no dominio de onboarding. cada type nao poderia ter um repo (unique key) como repo challenge apenas apontando pro repo (1:1)*? isso ainda permitiria excluir os repos de challenge das contribuições

*1 type aponta para 1 repo de challenge

guisaliba · 2026-06-24T04:04:52Z

+| **OnboardingFlow** | The per-type handler (a class behind the `OnboardingFlow` contract). Declares `steps()`, `prerequisites()`, `advance()`, `isComplete()`. All type-specific rules live here.     | The model — the Flow is stateless behaviour; the Onboarding is the state       |
+| **OnboardingStep** | One auditable stage of a flow, one row in `onboarding_steps`. Carries its own `status` + `data` (jsonb) + `completed_at`. Enables pause/resume and history.                     | A prerequisite (another _type_ that must be complete first)                    |
+| **Prerequisite**   | Another `OnboardingType` that must be **completed** before this one can start (e.g. `Squads` requires `Welcome`). Declared by the flow, enforced on start.                      | A step (intra-type) — a prerequisite is inter-type                             |
+| **APTO**           | Domain shorthand for "completed the `Squads` onboarding". The condition that unlocks squad candidacy and squad creation. It is _not_ a global flag — it is `Squads` completion. | A generic "active member" — APTO is specifically squad-eligible                |


APTO ta amarrado ao contexto do onboarding de Squads ou pretendemos reutilizar esse shorthand pra futuros onboarding types? se pretendemos reutilizar acho bom ja desamarrarmos os conceitos

guisaliba · 2026-06-24T04:11:25Z

+### Modelo
+
+- `squads` (`status`: `draft`/`active`/`inactive`/`archived`, `objective`, `slug`, tenant-scoped).
+- `squad_members` (pivot): `role` (`Captain`/`SubCaptain`/`Member`/`ExMember`), `joined_at`, `left_at`.


Sailor (marujo) ao inves de Member se quiserem que o schema esteja bem aderido ao tema de piratas, xd

guisaliba · 2026-06-24T04:14:43Z

+### `squads`
+
+`name`, `slug`, `objective` (text, nullable — `draft` pode não ter), `status` (`SquadStatus`
+`draft`/`active`/`inactive`/`archived`, default `draft`), timestamps.


created_by pra auxiliar a encontrar o autor do squad no futuro (utilidade)

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 requested changes Jun 17, 2026

View reviewed changes

docs(squads): apply new questioning

36262a8

Co-authored-by: Sther <72408918+stherzada@users.noreply.github.com> Signed-off-by: Daniel Reis <danielhe4rt@gmail.com>

stherzada previously approved these changes Jun 21, 2026

View reviewed changes

gvieira18 requested changes Jun 22, 2026

View reviewed changes

guisaliba reviewed Jun 24, 2026

View reviewed changes

feat(integration-github): emit domain event GithubPullRequestApproved

3079a6f

Re-Gouveia-QA dismissed stherzada’s stale review via 3079a6f June 25, 2026 23:24

Uh oh!

Conversation

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

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Clintonrocha98 commented Jun 19, 2026

Uh oh!

stherzada commented Jun 21, 2026

Uh oh!

stherzada commented Jun 21, 2026

Uh oh!

danielhe4rt commented Jun 21, 2026

Uh oh!

stherzada left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

danielhe4rt commented Jun 16, 2026 •

edited

Loading