Brain· Mukutu

Governança Mukutu

Recurso Em desenvolvimento

Governança Mukutu / Mukutu Governance

Novo formato de governança dos projetos da Mukutu, no monorepo mktvirtual/mukutu-mono. Líder: Gabriel Fonseca. Fonte: mukutu-mono.

A ideia central / Core idea

Workflow não-PR, event-driven. Os contratos dos projetos evoluem por um ciclo de Version materializado em git tags (padrão CloudEvents 1.0), não por branch + code review. O log de eventos é append-only — main nunca recebe force-push.

Design-first / Design-first

Rascunha-se o contrato em MDX no EventCatalog (apps/catalog/) antes de escrever código. Só depois de selar a Version (mukutu version complete) o código segue. Um hook (PreToolUse) bloqueia edição no catálogo sem uma VersionStarted aberta para a entidade.

Armazenamento de eventos em 3 camadas / 3-tier event storage

  • Tier 1 — git tags anotadas: marcos (version.started, version.completed, skill.registered, report). Convenção: <event-type>/<entity-id>/v<semver>.
  • Tier 2 — git notes (refs/notes/{events,snapshots,telemetry}): repetíveis (drafts, snapshots, payloads de contexto).
  • Tier 3 — SQLite local (~/.mukutu/events.db): runtime denso (invocações de skill, tool calls). Reconstruível, não autoritativo.

Catálogo de arquitetura (design-of-record) / Architecture catalog

apps/catalog/ roda EventCatalog. 5 domínios:

  • Platform — workflow + CLI.
  • System — integrações externas (MLflow, OpenObserve, Claude Code, Coolify, GitHub, Anthropic).
  • Skills — registro de skills (ver Skills da Equipe Mukutu).
  • MktFunnel — pipeline de dados multi-tenant (Reportei → S3/Postgres → dbt → Metabase).
  • Manager — kanban-core da Ana Julia (absorvido de anajuliabravo/dashs-projetos): queries GetCFD, GetThroughput, GetCycleTimeScatterplot, GetMonteCarloForecast. Liga direto a Lean & Flow e De Horas para Flow.

CLI única / Single CLI

mukutu (em projects/mukutu-cli/, Python Polylith) — 12 subapps: convention, entity, events, gate, kernel, obs, resolve, schema, skill, telemetry, version, versions. Cold start ~50ms.

Reports como eventos / Reports as events

Artefatos de pesquisa/decisão = HTML standalone em docs/reports/ + git tag. Versionados em semver (nascem v0.1.0). Um report = um contexto de decisão auditável.

Stack & deploy

  • Python: uv + polylith-cli. JS/TS: pnpm workspaces + catalogs. Toolchain: mise.
  • Deploy: Coolify v4 (coolify.mukutu.cloud). Observabilidade: OpenObserve + MLflow.

Por que importa para a Nova Mukutu / Why it matters

  • É a espinha dorsal técnica da transformação: governança auditável, design-first e orientada a eventos.
  • O domínio Manager conecta a governança ao novo formato de fluxo (De Horas para Flow, Lean & Flow).

Perguntas a responder / Questions to answer

  • Como a equipe não-dev adota o fluxo via git tags sem fricção?
  • Qual o papel da Ana no domínio Manager daqui pra frente?

Relacionado / Related

Fontes / Sources