# docs/fluxo.yml — modelo-alvo do time de entrega (v3) # Decisão estrutural: ADR 0085. Peças irmãs: docs/gates.yml (controle, # ADR 0054) e apps/api/src/domain/agents/agent-areas.ts (catálogo). # # status de papel: # active opera hoje, com RN/ADR citada # planned contrato pronto, ativação decidida, aguarda gatilho # proposto papel do modelo-alvo, hoje absorvido por outro, # com critério objetivo de separação declarado # em-refinamento código ativo, fora do fluxo formal até o dono do # produto redefinir os entregáveis version: 3 camada_autoridade: - id: usuario status: active entregaveis: [decisao-de-merge (RN-014), promocao-de-story (RN-048), aprovacao-de-proposed-action, plano-de-adocao (RN-045/046), autorizacao-de-paralelismo (RN-083/086), decisao-que-retoma-laco (ADR 0052/0057), dispensa-com-justificativa] camada_produto: - id: criativo papel_de_mercado: discovery / entrada de negócio status: active teto: 12 entradas: [{ artefato: conversa-livre, origem: usuario }] saidas: [{ artefato: necessidade-de-negocio, destino: po, via: handoff }] ferramentas: [ask_structured_questions] # RN-162/171 gate_saida: { id: necessidade-validada, status: ativo, aprovacao_humana: true, regra: RN-657 } # ADR 0095, revisto pelo 0185 anti_padrao: solução disfarçada de problema - id: ux-designer papel_de_mercado: UX / Product Designer status: active teto: 14 # Ativado antes do gatilho original ter disparado (ADR 0087, decisão # consciente do dono do produto) — histórico do que o papel absorvia: # criativo (discovery) + design/ (design system como dado estático). O # design system CONTINUA estático (sem tool de leitura de repo pros # agentes conversacionais); o que mudou é o protótipo virar entregável # de agente, não mais implícito na conversa do Criativo. entregaveis: [personas-e-jornadas, prototipo-navegavel] # teste-de-usabilidade fica FORA de alcance: exige usuário humano real, # não um agente. metricas-de-uso segue lacuna — depende do papel # analytics, que continua proposto. entradas: [{ artefato: necessidade-de-negocio, origem: criativo }, { artefato: metricas-de-uso, origem: analytics, status: lacuna }] # Handoff manual (ADR 0109, RN-440/441): entrou em AGENTES_DE_CHAT e no # seletor de SessionPage.tsx — o mecanismo já era genérico, faltava só # a tela saidas: [{ artefato: prototipo, destino: po }, { artefato: spec-visual, destino: dev-lead }] ferramentas: [propose_prototype] gate_saida: { id: prototipo-validado, status: proposto } - id: po papel_de_mercado: PO/PM status: active teto: 12 entradas: - { artefato: necessidade-de-negocio, origem: criativo } - { artefato: regras-e-backlog, origem: leitura-escopada } # RN-164 - { artefato: metricas-de-produto, origem: analytics, regra: RN-407 } saidas: - { artefato: epico, destino: backlog, obrigacao: RN-165 } - { artefato: historia, destino: usuario, via: proposed_ready } - { artefato: tarefa, destino: dev, via: backlog } # RN-179 gate_saida: { id: story-promovida, status: ativo, aprovacao_humana: true } - id: analytics papel_de_mercado: Analytics Engineer (métrica de PRODUTO) status: active forma: script (nunca agente — ADR 0089), "analise:funil" entregaveis: [funil-sessao-commit-pr-merge, lead-time-real, deployment-frequency-real] saidas: [{ artefato: relatorio-de-funil, destino: [po, ux-designer] }] lacunas: [{ artefato: metricas-de-produto-completas, status: lacuna, motivo: "sessions sem storyId — RN-230" }, { artefato: evidencia-de-adocao-por-feature, status: lacuna, motivo: "sem caminho hoje — Brabo não instrumenta o que constrói" }] camada_decisao_tecnica: - id: arquiteto papel_de_mercado: Arquiteto de software status: active teto: 14 entradas: - { artefato: backlog-promovido, origem: po } - { artefato: rfc-e-poc, origem: staff, status: planned } - { artefato: telemetria-consolidada, origem: platform, status: planned } - { artefato: threat-model, origem: appsec, status: proposto } saidas: - { artefato: module_map, destino: [dev-lead, area-dev] } # RN-159 - { artefato: artifact.project_image, destino: aba-code } # RN-105 - { artefato: artifact.c4_diagram, destino: visao-geral } # RN-149 - { artefato: artifact.module_contracts, destino: area-dev } # RN-684 - { artefato: artifact.module_routing, destino: area-infra, nota: "candidata; quem elege é a Infra, PR à parte" } # RN-487 - { artefato: handoff, destino: area-infra, pre_condicao: RN-160 } # "Confirmar arquitetura pronta" exige história promovida # o handoff ao dev-lead saiu daqui na RN-672 (ADR 0190): quem o oferece é a area-infra - { artefato: nfrs-mensuraveis, destino: [dev-lead, qa-estrategia, platform], status: proposto, regra: NFR sem como-medir é inválido } gate_saida: { id: adr-aprovado, status: proposto } fronteira: decisão que cabe num PR revertível NÃO é dele - id: dev-lead papel_de_mercado: Tech Lead status: active teto: 14 entradas: - { artefato: handoff, origem: area-infra, pre_condicao: "container do projeto running", regra: RN-672, nota: "aceitar encadeia ativação de execução quando o papel efetivo já autoriza — RN-161" } - { artefato: module_map, origem: arquiteto } # RN-159 # plano-de-teste saiu daqui no ADR 0192 (RN-674): nasce DEPOIS da # entrega do dev e entra no qa-verificada; o parecer de # implementabilidade se julga sobre a história e o module_map acima - { artefato: threat-model, origem: appsec, status: proposto } - { artefato: parecer-de-migracao, origem: dbre, status: proposto } saidas: - { artefato: plano-de-paralelismo, destino: usuario, via: proposed_action, regra: RN-083/154 } - { artefato: parecer-implementabilidade, destino: usuario, via: proposed_action, regra: RN-340 } # ADR 0090 - { artefato: delegacao, destino: dev, status: ativo, regra: RN-405 } # ADR 0094 - { artefato: design-doc + quebra-tecnica, destino: dev, status: proposto } gates: - { id: paralelismo-autorizado, status: ativo } - { id: implementavel, status: ativo } # ADR 0090 - id: staff papel_de_mercado: Staff/Principal Engineer status: planned codigo: pronto (staff_server.ex, staff_tools.ex, staff_supervisor.ex — ADR 0088) — acionável MANUALMENTE por handoff aceito endereçado a "staff", mecanismo GENÉRICO (sem entrar em USER_STARTED_AGENTS) ativacao: gatilho AUTOMÁTICO (problema sistêmico RECORRENTE registrado pela anamnese) segue pendente enquanto ANAMNESE_ENABLED=false — dormente para disparo automático, não para acionamento manual. Acionamento manual ganhou TELA (ADR 0109, RN-440/441) — seletor em SessionPage.tsx, rota POST .../sessions/sessionId/handoffs entregaveis_alvo: [rfc, poc-descartavel, parecer-sistemico] saidas_alvo: [{ artefato: rfc + poc, destino: arquiteto }] camada_execucao: - id: dev papel_de_mercado: Engenheiro de software status: active tipo: execucao (teto 60, RN-085) · area dinâmica, um por módulo entradas: [{ artefato: tarefa, origem: backlog }, { artefato: worktree-por-agente, origem: dev, nota: "provisionado por Engine.Dev.WorktreeManager — não é um dos 4 componentes do harness (achado A8)" }, { artefato: design-doc, origem: dev-lead, status: proposto }] saidas: - { artefato: branch-rastreavel } # RN-152 - { artefato: pr-remota, destino: [area-qa, secops], via: acao-tipada } - { artefato: eventos-instrumentados, destino: medicao } maquina_de_estados: working|awaiting_approval|awaiting_gate|idle|idle_tripped # RN-047; awaiting_approval entrou na Fase 12e (ADR 0052) — achado A3 camada_qualidade: - id: qa-estrategia papel_de_mercado: QA Engineer (estratégia de teste da entrega) status: active # ADR 0090 absorvido_por: > area-qa — é o próprio qa-lead (Engine.Gates.QaLeadServer), SEGUNDO momento, mesmo processo, entregável separado do veredito de PR — nunca agente novo. Desde o ADR 0192 (RN-674) o momento é DEPOIS da entrega do dev, no começo do ciclo do qa-verificada, e não mais no design: no uso real de 29/09 o plano PRE-DEV esgotou o teto (8) procurando um código que ainda não existia entradas: - { artefato: story, origem: po } # via backlog - { artefato: entrega (worktree + diff contra dev), origem: dev } # ADR 0192 entregaveis: [plano-de-teste-por-entrega, criterio-executavel, estrategia-de-automacao] saidas: [{ artefato: plano-de-teste, destino: area-qa }] # ADR 0192 gate_saida: { id: qa-verificada, status: ativo, nota: "insumo, não veredito próprio" } - id: area-qa papel_de_mercado: SDET + QA de execução status: active estrutura: qa-lead + qa-automacao + qa-perf-seguranca (ADR 0038) entradas: [{ artefato: pr-remota, origem: dev }, { artefato: plano-de-teste, origem: qa-estrategia }] # ADR 0192 internas: [delegacao-privada, suspensao-retomada-por-decisao (13b), falha-com-origem-ao-lead] saidas: [{ artefato: veredito-qa, destino: gates }] gate_saida: { id: qa-verificada, status: ativo } achado_aberto: AE (decisão de produto) camada_seguranca: - id: appsec papel_de_mercado: AppSec (segurança no DESIGN) status: active estrutura: mesmo padrão do QA — dois MOMENTOS, não dois agentes por ora. Quem roda é o MESMO processo do secops (`Engine.Gates.SecOpsAgentServer`), num segundo momento — `run_design/2`, sem worktree/task_id, threat model STRIDE-lite sobre a story + module_map, ANTES de existir código/PR (RN-360, ADR 0090). Agente separado continua fora de escopo, só com produção real. entradas: - { artefato: story + module_map, origem: [po, arquiteto] } saidas: - { artefato: threat-model, destino: [arquiteto, dev-lead, infra] } # RN-360 entregaveis_alvo: [politica-de-supply-chain] # herdado do secops hoje (SBOM/dependabot), sem mecanismo novo acionamento: > assess_implementability do Dev Lead (gate implementavel) — o gatilho natural que esta linha declarava como lacuna, agora implementado (RN-539). O appsec SEGUE no design depois do ADR 0192: a decisão do dono que tirou o plano de teste do pre-dev foi sobre o QA. Ao avaliar uma story, run_assessment/2 (apps/engine/lib/engine/agents/dev_lead_tools.ex) chama Engine.Gates.Dispatcher.run_appsec_design/2, que sobe o SecOpsAgentServer do projeto e faz run_design/2. Dispara em PARALELO, nas DUAS saídas do parecer, e NUNCA bloqueia: o parecer de implementabilidade não espera pelo threat model. Idempotente — só dispara para story que ainda não tem artifact.threat_model, senão cada retentativa do modelo custaria outra rodada de LLM e mais três handoffs (RN-361). Segue sem rota HTTP: nenhum humano aciona o appsec direto, por decisão. - id: secops papel_de_mercado: SecOps (veredito na PR) status: active entradas: [{ artefato: pr-remota, origem: dev }] saidas: [{ artefato: veredito-secops, destino: gates }] gate_saida: { id: secops-segura, status: ativo } - id: secops-runtime papel_de_mercado: detecção e resposta status: active entradas: [{ artefato: rate-limit-hits, origem: rate-limit-guard }] entregaveis: - { artefato: deteccao, forma: relatorio-de-abuso-sobre-rate-limit-hits, via: script, status: active } # ADR 0091, RN-375..378 - { artefato: resposta-a-incidente, status: lacuna, motivo: exige tráfego de produção real (pós DEPLOY_ENABLED + platform ativo) } - { artefato: postmortem-de-seguranca, status: lacuna, motivo: exige tráfego de produção real (pós DEPLOY_ENABLED + platform ativo) } saidas: [{ artefato: relatorio-de-abuso, destino: usuario, via: script }] criterio_de_separacao: > Detecção AUTOMÁTICA (alarme sobre tráfego contínuo), resposta a incidente e postmortem continuam exigindo produção com tráfego real (pós DEPLOY_ENABLED + platform ativo) — o script acima só relata, sob demanda, o padrão já coletado em rate_limit_hits. camada_plataforma: - id: area-infra papel_de_mercado: DevOps/Infra Engineer status: active estrutura: infra-lead + infra-workflows (CI por provider, ADR 0039) entradas: [{ artefato: handoff, origem: arquiteto }, { artefato: threat-model, origem: appsec, status: proposto }, { artefato: artifact.module_routing, origem: arquiteto, nota: "a Infra elege (ADR 0133); no aceite, o servidor elege e sobe (RN-671)" }] saidas: [{ artefato: ci-workflows, destino: repositorio }, { artefato: proposta-de-infra, destino: usuario }, { artefato: container-do-projeto, destino: dev-lead, via: proposed_action, regra: RN-671, nota: "o servidor propõe no aceite; container_start semeado auto_approve (ADR 0190)" }, { artefato: handoff, destino: dev-lead, regra: RN-672, pre_condicao: "container do projeto running", nota: "passo do servidor: fim de turno da Infra ou container.running do outbox" }, { artefato: pipeline-verde, destino: platform, status: planned }] gate_saida: { id: deployavel, status: planned } # DEPLOY_ENABLED - id: bots-release-gate papel_de_mercado: automação de release status: active saidas: [tag-calculada, release-gate-json, backmerge-retropropagado] gates: [{ id: merge-protegida, evidencia: teste }, { id: backmerge, evidencia: ci }] - id: platform papel_de_mercado: SRE / Platform — dono do loop de retorno status: planned ativacao: sincronizada com DEPLOY_ENABLED entradas_alvo: [{ artefato: pipeline-verde, origem: area-infra }, { artefato: nfrs-mensuraveis, origem: arquiteto }] saidas_alvo: - { artefato: slo + dashboard + runbook, destino: gates } - { artefato: telemetria-consolidada, destino: arquiteto, nota: "a versão MANUAL/sob-demanda já é REAL — script (relatorio:telemetria, RN-385/386, ADR 0092), lendo as mesmas fontes do DomainGaugesCollector; a versão AUTOMÁTICA, em loop fechado, segue pendente do gatilho (DEPLOY_ENABLED)" } - { artefato: postmortem, destino: [arquiteto, po] } gate_saida: { id: operavel, status: planned } - id: dbre papel_de_mercado: DBA / Database Reliability status: active hoje_absorvido_por: dev-lead (aprova o schema com o parecer em mãos) + platform (tuning, quando ativar) — o que resta absorvido por eles é só plano-de-capacidade/tuning; UMA migration por onda continua sendo a trava de CONFLITO entre agentes, não o parecer de risco (esse agora é mecânico, ver entregaveis) criterio_de_separacao: volume real de dados no projeto gerenciado — plano-de-capacidade e tuning dependem dele; o parecer de risco de SCHEMA e o relatório de backup NÃO dependem, por isso já são reais entregaveis: - { artefato: parecer-de-migracao, status: real, mecanismo: "pnpm --filter api lint:migracao" } - { artefato: backup-restore-testado, status: real, mecanismo: "pnpm --filter api relatorio:backup + docs/runbook.md#restore" } - { artefato: plano-de-capacidade, status: lacuna, motivo: exige volume real de dados } - { artefato: tuning, status: lacuna, motivo: exige volume real de dados } saidas: [{ artefato: parecer-de-migracao, destino: dev-lead }] camada_instrumentos: - id: medicao papel_de_mercado: Data Engineer (métrica de EXECUÇÃO) status: active ferramentas: ["medir:execucao", "validacao:gates", "validacao:real", sumGroupedBy] saidas: [{ artefato: metricas-de-execucao, destino: usuario }] nota: métrica de PRODUTO é do papel analytics (camada produto) - id: harness papel_de_mercado: Delivery Manager (orquestração) status: active componentes: [PromptAssembler, ToolLoop, ContextManager, Hooks] invariantes: [nada-fora-do-harness, tetos-por-tipo (RN-085), laco-nunca-calado (RN-166)] - id: delivery-metricas papel_de_mercado: Delivery Manager (fluxo — DORA) status: active criterio_de_separacao: nunca vira agente — é RELATÓRIO do medicao ("analise:funil", ADR 0089) entregaveis: [lead-time-real, deployment-frequency-real] saidas: [{ artefato: relatorio-dora-parcial, destino: usuario }] lacunas: [{ artefato: mttr, status: lacuna, motivo: "exige sinal de incidente real — secops-runtime/platform" }, { artefato: change-failure-rate, status: lacuna, motivo: "mesma dependência de mttr" }] camada_transversal: - id: psicologo status: em-refinamento # decisão do dono do produto entregaveis_congelados: [hipotese-com-chips-de-evidencia] - id: anamnese status: em-refinamento entregaveis_congelados: [proposta-de-ajuste-3-aprovacoes-zero-negacao] pendencias_da_suspensao: [autor-da-proposta-de-teto (RN-086), gatilho-de-ativacao-do-staff] removidos: - { papel: engineering-manager, decisao: removido-pelo-usuario }