atlas-workflow 0.8.2

package/plugins/atlas-workflow-orchestrator/templates/BOUNDARY_PRD_PLAN.md

@@ -0,0 +1,93 @@
+# Fronteira PRD × PLAN
+
+Política documental para sprints e handoff de execução. Referência: exemplos em [PRD/GARANTIAFACIL/EXEMPLO/](../PRD/GARANTIAFACIL/EXEMPLO/).
+
+## Papéis
+
+| Artefato | Dono mental | Pergunta que responde |
+|----------|-------------|------------------------|
+| **PRD** | Product Manager | O quê, por quê, para quem, o que não pode quebrar? |
+| **PLAN** | Engenharia / executor | Como entregar no código, em que ordem, com que invariantes técnicos? |
+
+## PRD — o que entra (modelo enxuto de 6 seções + apêndice)
+
+- **§1 Contexto e objetivo** — hoje, impacto de não fazer, objetivo, resultado observável, sucesso.
+- **§2 Escopo** — em escopo / fora de escopo (sem "Não objetivos"; invariante vira §5).
+- **§3 Decisões de produto (D\*)** — casa única; demais seções referenciam por `D-id`.
+- **§4 Fluxos e cenários UX** — por cenário, com loading/vazio/erro.
+- **§5 Contrato funcional e invariantes** — regras de dados + invariantes de negócio/segurança numa casa só.
+- **§6 Critérios de aceite (negócio)** — checklist testável (Produto/UX/Dados/Regressão).
+- **§7 Apêndice (opcional)** — riscos, dependências, referências, histórico.
+
+> **Regra anti-repetição:** cada verdade tem uma casa; as demais seções referenciam por `§`/`D-id`, não re-enumeram.
+
+## PRD — o que NÃO entra
+
+- Packages, camadas, clean architecture, GetX, nomes de classes/arquivos.
+- `flutter analyze`, comandos de teste, paths do monorepo.
+- Tabela “evidências” com dezenas de arquivos `.dart`.
+- § “Impacto de arquitetura” — isso é PLAN.
+- Repetir o conteúdo do PLAN.
+
+**Teto orientativo:** ~120–150 linhas por sprint média (modelo enxuto).
+
+## PLAN — o que entra
+
+- Link ao PRD + referência `PRD §3` (não recopiar tabela D* inteira).
+- Tradução executiva (padrão de referência no monorepo + diffs vs módulo espelho).
+- Invariantes de **execução** derivados do PRD.
+- Pitfalls (anti-padrão → correto).
+- Estado na **abertura da sprint** (3–6 bullets); se já implementado, checklist de verificação.
+- **Tarefas T01…** no schema abaixo (detalhadas).
+- Contratos técnicos só onde o PRD deixa ambiguidade.
+- Validação única + checklist do validator.
+- **Slices** (opcional) se `execution_mode: orchestrated-per-slice`.
+
+## PLAN — o que NÃO entra
+
+- Handoff prompt no final (“leia o plano e execute…”).
+- Gate de prontidão do autor do plano.
+- Lista §3 com todas as rules do `project-rules` (o executor carrega AGENTS).
+- Cópia integral do escopo/fora de escopo do PRD.
+- Inventário global de todos os arquivos tocados (o executor descobre no repo).
+- Duplicar três checklists idênticas.
+
+**Teto orientativo:** ~250–350 linhas (M); até ~450 (L com slices).
+
+## Herança entre documentos
+
+```text
+PRD §3 (D*)  ──referência──►  PLAN §2 invariantes + §1 diffs
+PRD §4–6     ──referência──►  PLAN §5 (done) + §8 checklist
+PRD §5       ──funcional──►  PLAN §6 contratos técnicos
+```
+
+## Schema de task (PLAN §5)
+
+Cada `#### TNN.` deve ter, quando aplicável:
+
+- **Objetivo**
+- **Referência** (módulo/padrão no monorepo — não lista de 10 arquivos)
+- **Pré-condições**
+- **Mudança esperada**
+- **Invariantes preservados** / **Não mudar** / **Não fazer**
+- **Dependências**
+- **Riscos** (se não óbvio)
+- **Critério de done**
+- **Validação local** (comando — na task de teste ou na final)
+- **Quality gates** (opcional em tasks críticas)
+- **Casos mínimos** (tasks de teste)
+
+## Templates
+
+- [PRD_TEMPLATE.md](./PRD_TEMPLATE.md)
+- [PLAN_TEMPLATE.md](./PLAN_TEMPLATE.md)
+- [BACKLOG_MESTRE_TEMPLATE.md](./BACKLOG_MESTRE_TEMPLATE.md)
+
+## Pipeline
+
+1. PRD aprovado (produto).
+2. PLAN derivado do PRD + código (uma passagem de leitura no repo).
+3. Execução: `atlas-plan-execute` lê PLAN + PRD §4–6; `project-rules` via AGENTS.
+
+Geradores (`atlas-backlog-generator`, `atlas-sprint-prd-generator`, `atlas-plan-handoff`) devem seguir estes templates, não o formato legado (14 seções, ou §X de arquitetura no PRD).

package/plugins/atlas-workflow-orchestrator/templates/PERGUNTAS_EM_ABERTO_TEMPLATE.md

@@ -0,0 +1,139 @@
+# Perguntas em aberto — {{NOME_DO_PROJETO}}
+
+> **Função deste arquivo:** inventário do que ainda precisa de decisão sua (produto, operação, sequência), com foco no horizonte imediato do backlog.  
+> **O que NÃO vai aqui:** opções A/B/C, recomendações, raciocínio longo — isso nasce **na entrevista**, com backlog, código e docs relidos na hora (`*-open-questions-interview` ou pedido explícito de rodada).
+
+---
+
+## Como usar (dois modos)
+
+| Modo | Quem | O que faz | Saída |
+|------|------|-----------|--------|
+| **Varredura** | Agente (ou você) | Cruza backlog mestre, recorte das próximas sprints, PRDs e planos quando existirem, código e contratos; abre/atualiza/fecha **entradas** no índice | Este arquivo (enxuto) |
+| **Entrevista** | Você + agente | Escolhe **1–4 IDs** `aberta`; agente relê âncoras + repositório; pergunta com **AskQuestion** | Decisão no chat → linha no **Histórico** → PRD/backlog/DEC |
+
+**Regra anti-desatualização:** antes de cada rodada de entrevista, o agente **revalida** as âncoras e o código dos IDs escolhidos. Se a evidência mudou, atualiza a lacuna no registro **antes** de perguntar.
+
+**Formato de resposta na entrevista:** `Q-XXX → A` ou `Q-XXX → Outro: …`
+
+**Legenda de severidade:** `❌` bloqueia handoff/implementação honesta · `⚠️` permite avançar com risco documentado  
+
+**Status:** `aberta` · `em entrevista` · `resolvida` · `adiada` · `obsoleta` (código/docs já fecharam o tema)
+
+**Janela de análise:** sprint atual + próximos sprints do backlog, com máximo de 5 sprints no total.
+
+---
+
+## Meta
+
+| Campo | Valor |
+|-------|-------|
+| **Última varredura** | YYYY-MM-DD |
+| **Escopo da varredura** | ex.: backlog mestre §20, PRD HML-01 se existir, sprints S04–S08 |
+| **Próxima rodada sugerida** | IDs: `Q-…`, `Q-…` (máx. 4 por sessão ~15 min) |
+
+---
+
+## Índice
+
+<!-- Uma linha por decisão pendente. Manter ordenado por urgência ou fase. Preferir poucas perguntas fortes a volume. -->
+
+| ID | Título curto | Severidade | Bloqueia | Status |
+|----|--------------|------------|----------|--------|
+| Q-XXX-01 | … | ❌ | … | `aberta` |
+
+**Totais:** `aberta` __ · `em entrevista` __ · `adiada` __
+
+---
+
+## Entradas
+
+<!-- Copie o bloco abaixo por item. Não incluir tabelas de opções nem "Recomendação". Serializar categoria no título, ex.: [contrato] Nome da decisão. -->
+
+### Q-XXX-01 — Título da decisão
+
+| Campo | Valor |
+|-------|-------|
+| **Status** | `aberta` |
+| **Severidade** | ❌ / ⚠️ |
+| **Bloqueia** | sprint, PRD, gate, contrato — uma linha. Se útil, prefixar categoria secundária: `[sequencia] ...` |
+| **Âncoras** | links relativos: backlog mestre, sprint, PRD se existir, DEC, plano, doc de produto, código ou contrato |
+| **Lacuna** | O que falta decidir (2–4 frases). Sem listar alternativas. Descrever decisão pendente, não tarefa de implementação. |
+| **Evidência (snapshot)** | Uma linha factual da última varredura (path, migration, status sprint, endpoint, env ou ausência verificável) |
+| **Última verificação em entrevista** | _vazio até 1ª rodada_ |
+
+**Decisão registrada:** _preencher só após entrevista_  
+**Propagado em:** _PRD §… / backlog DEC-… / outro_
+
+---
+
+### Q-XXX-02 — …
+
+| Campo | Valor |
+|-------|-------|
+| **Status** | `aberta` |
+| **Severidade** | ⚠️ |
+| **Bloqueia** | … |
+| **Âncoras** | … |
+| **Lacuna** | … |
+| **Evidência (snapshot)** | … |
+| **Última verificação em entrevista** | |
+
+**Decisão registrada:**  
+**Propagado em:**
+
+---
+
+## Histórico de resoluções
+
+| Data | ID | Decisão (resumo) | Onde propagado |
+|------|-----|------------------|----------------|
+| | | | |
+
+---
+
+## Evidências da última varredura
+
+<!-- Lista de paths consultados — sem narrativa longa. Atualizar a cada varredura. Registrar também ausências verificáveis relevantes. -->
+
+- `…`
+- `…`
+
+---
+
+## Protocolo do agente
+
+### Varredura (atualizar registro)
+
+1. Ler obrigatoriamente o backlog mestre e o recorte da janela atual; usar PRDs e planos apenas quando existirem.
+2. Limitar a análise ao sprint atual e aos próximos sprints, com máximo de 5 sprints no total.
+3. Revalidar código, contratos, migrations, envs ou ausências verificáveis antes de abrir pergunta material.
+4. Para cada lacuna nova: criar entrada com ID estável (`Q-<FASE>-<NN>` ou `Q-<SPRINT>-<NN>`).
+5. Antes de abrir pergunta, tentar invalidá-la: decisão já tomada, código já fechou o tema, falta apenas execução, ou a dúvida existe só porque não há PRD.
+6. Para cada lacuna fechada no código/docs: marcar `obsoleta` ou remover do índice e notar no Histórico.
+7. Atualizar **Meta**, **Índice**, **Evidências**; **não** escrever opções nem recomendações.
+
+### Entrevista (uma rodada)
+
+1. Usuário indica 1–4 IDs (ou aceita "próxima rodada sugerida").
+2. **PREP:** reler âncoras + grep/read nos paths relevantes; ajustar **Lacuna** / **Evidência** se mudou.
+3. **PERGUNTA:** `AskQuestion` (até 4 itens); em cada prompt: pergunta + impacto + opções + **recomendação ancorada na evidência lida agora** (skill `*-open-questions-interview`).
+4. Parar o turno (`⏸️ Aguardando respostas`).
+5. Após respostas: preencher **Decisão registrada**, status `resolvida`, linha no **Histórico**, pedir propagação explícita se necessário (backlog DEC, PRD §3, etc.).
+
+### O que é proibido neste arquivo
+
+- Tabelas `| Opção |` ou blocos **Recomendação** / **Opção A/B/C** por pergunta
+- Texto de entrevista já "respondido" no passado sem estar no Histórico
+- Duplicar o conteúdo do PRD — só âncoras e lacuna
+- Criar novos campos, colunas ou seções para categoria; use a serialização textual nos campos existentes
+
+---
+
+## Agrupamento opcional (âncoras de navegação)
+
+<!-- Títulos `##` por fase/sprint/bloco; entradas `###` abaixo. O índice único continua sendo a fonte de IDs. -->
+
+## {{FASE_OU_BLOCO}} — …
+
+_(entradas Q-… deste bloco)_

package/plugins/atlas-workflow-orchestrator/templates/PLAN_TEMPLATE.md

@@ -0,0 +1,146 @@
+# PLAN <ID> — <Título> (execução)
+
+| Campo | Valor |
+|-------|-------|
+| **PRD** | [PRD_<ID>_<slug>.md](./<caminho-relativo>) — decisões **PRD §3** (D*) |
+| **Package / app** | `<packages/... \| apps/...>` |
+| **Tipo** | `<feature \| ui \| navigation \| …>` |
+| **execution_mode** | `<sequencial (T01→TN) \| orchestrated-per-slice>` |
+| **Data** | <YYYY-MM-DD> |
+
+**Escopo técnico:** PRD §2. **Fora:** <bullets derivados do PRD fora de escopo — não recopiar §2 inteiro>.
+
+Política: [BOUNDARY_PRD_PLAN.md](./BOUNDARY_PRD_PLAN.md). Exemplos: [PRD/GARANTIAFACIL/EXEMPLO/](../PRD/GARANTIAFACIL/EXEMPLO/).
+
+---
+
+## 1. Tradução executiva
+
+<O que será implementado em 1 parágrafo + resultado observável técnico.>
+
+**Padrão de referência no monorepo:** <ex.: “espelhar módulo X em …”>
+
+**Diferenças obrigatórias vs referência (não copiar cegamente)**
+
+| Tema | Referência (rejeitar) | Esta entrega (PRD) |
+|------|----------------------|-------------------|
+| <…> | <…> | <D* ou regra> |
+
+<Capacidades já existentes no código que esta slice só integra — ex.: use cases GF04 prontos.>
+
+---
+
+## 2. Invariantes de execução (derivados do PRD)
+
+- <invariante técnico derivado de PRD §3/§5 — ex.: sem refetch ao filtrar>
+- <…>
+
+> Não recopiar a tabela de decisões do PRD; referenciar `PRD §3 D12`.
+
+---
+
+## 3. Pitfalls
+
+- <anti-padrão comum no repo> → <correção>
+- <…>
+
+---
+
+## 4. Estado na abertura da sprint (pré-implementação)
+
+> Se a entrega **já estiver no código**, não reimplementar: usar como checklist de verificação (diff vs §7). O executor **lê o repo** e confirma o que falta.
+
+- <3–6 bullets do que bloqueia hoje — comportamento ou ausência, não lista de 15 arquivos>
+
+---
+
+## 5. Tarefas de execução
+
+<!-- Para execution_mode: orchestrated-per-slice, agrupar com ### Slice A — … -->
+
+#### T01. <Título curto>
+
+- **Objetivo:** <resultado observável>
+- **Referência:** <módulo/padrão no monorepo — opcional>
+- **Pré-condições:** <nenhuma \| T0X>
+- **Mudança esperada:** <o que muda de forma concreta>
+- **Invariantes preservados:** <§2 ou PRD>
+- **Não mudar:** <…>
+- **Não fazer:** <atalhos proibidos>
+- **Dependências:** <nenhuma \| T0X>
+- **Riscos:** <se relevante>
+- **Critério de done:** <sinal objetivo>
+- **Validação local:**
+  ```bash
+  cd <package-ou-repo> && <comando>
+  ```
+- **Quality gates:** <opcional — itens verificáveis desta task>
+- **Casos mínimos:** <somente em tasks de teste — lista numerada>
+
+#### T02. <…>
+
+<repetir até TNN>
+
+#### TNN. Validação final
+
+- **Objetivo:** analyze + test suite; regressão de entregas dependentes; aceite manual mínimo (PRD §6).
+- **Dependências:** T01–T(N-1)
+- **Critério de done:** zero issues; testes verdes
+- **Validação local:**
+  ```bash
+  cd <package> && flutter analyze
+  cd <package> && flutter test
+  ```
+- **Verificação manual (recomendada):**
+  1. <passo alinhado ao PRD §4>
+  2. <…>
+
+---
+
+## 6. Contratos técnicos (só ambiguidade PRD → código)
+
+### 6.1 <Domínio / persistência / API>
+
+| <Camada> | Regra |
+|----------|--------|
+| <…> | <…> |
+
+### 6.2 <Falhas / estados / pipeline — se aplicável>
+
+| <Code ou etapa> | <Comportamento na store/UI> |
+|-----------------|----------------------------|
+
+---
+
+## 7. Slices (somente se `execution_mode: orchestrated-per-slice`)
+
+| Slice | Tasks | Objetivo |
+|-------|-------|----------|
+| A | T01–T03 | <…> |
+| B | T04–T05 | <…> |
+
+Ordem: **A → B → …**. Validator: boundary do diff por slice + §2 e §7.
+
+---
+
+## 8. Validação e checklist (validator)
+
+Referência **PRD §6** + invariantes **§2** deste plano.
+
+```bash
+cd <package> && flutter analyze
+cd <package> && flutter test
+```
+
+- [ ] <critério derivado de PRD D* ou §10>
+- [ ] <…>
+
+---
+
+## O que este template NÃO inclui (propositalmente)
+
+- Handoff prompt final
+- Gate de prontidão do planejador
+- § “Regras carregadas” do `project-rules` (AGENTS carrega)
+- Cópia da tabela D* do PRD
+- Inventário global de arquivos tocados

package/plugins/atlas-workflow-orchestrator/templates/PRD_TEMPLATE.md

@@ -0,0 +1,149 @@
+# PRD: <Nome da feature / Sprint>
+
+> **Documento de produto.** Comportamento e negócio — sem Dart, packages, paths ou comandos de CI.
+>
+> Comportamento **alvo** da entrega. Se a feature já estiver no app, use como contrato de aceite e regressão.
+>
+> Implementação: `PLAN_<ID>_<slug>.md` (gerado após PRD aprovado). Política: [BOUNDARY_PRD_PLAN.md](./BOUNDARY_PRD_PLAN.md).
+>
+> **Regra de ouro (anti-repetição):** cada verdade tem **uma casa**; as demais seções **referenciam** por `§`/`D-id` em vez de re-enumerar. Enxugar conteúdo nunca remove a demarcação (separadores, rótulos, subcabeçalhos).
+
+| Campo | Valor |
+|-------|-------|
+| **Produto / App** | <GarantiaFácil \| Assina \| Atlas host \| …> |
+| **Status** | <Draft \| Em decisão \| Aprovado para planejamento \| Aprovado para implementação \| Implementado \| Arquivado> |
+| **Responsável** | <Papel ou nome> |
+| **Data** | <YYYY-MM-DD> |
+| **Dependências de negócio** | <Entregas anteriores necessárias — ex.: “dashboard com lista”> |
+| **Relacionado** | <Regras de negócio, MVP, backlog §X, DEC-*, Q-* — links> |
+
+### Metadados de execução
+
+- Plan prefix: `<atlas>` · Planner: `<atlas-plan-handoff>` · Executor: `<atlas-plan-execute>`
+- Internal validator: `<atlas-task-validator>` · External review: `<atlas-slice-review>` (optional)
+
+---
+
+## 1. Contexto e objetivo
+
+**Hoje:** <comportamento atual em linguagem de usuário/negócio>
+
+**Se não entregar:** <impacto de não fazer>
+
+**Objetivo principal:** <uma frase>
+
+**Resultado observável**
+
+- <bullet observável pelo usuário ou operação — referencie D* em vez de re-enumerar entregáveis>
+
+**Sucesso (negócio):** <como saber que valeu — sem métrica técnica de CI>
+
+---
+
+## 2. Escopo
+
+### Em escopo
+
+- <capacidades fechadas, em linguagem de produto — referencie o conjunto de §3 D* quando aplicável>
+
+### Fora de escopo
+
+- <adjacentes tentadores que NÃO entram nesta entrega — previne scope creep>
+- <anti-goal oportunista ("não aproveitar para fazer X"); invariante que é regra de negócio vai para §5, não aqui>
+
+---
+
+## 3. Decisões de produto (fechadas)
+
+> Casa única das decisões. As demais seções referenciam por `D-id`, não recopiam.
+
+| ID | Decisão |
+|----|---------|
+| D1 | <decisão fechada — produto, não implementação. É a SSoT do que esta sprint entrega> |
+| D2 | <…> |
+
+> Motivo/impacto: só quando a decisão não for óbvia; senão omitir.
+
+---
+
+## 4. Fluxos e cenários UX
+
+> Quando vários cenários compartilham comportamento, declare uma vez e referencie.
+
+### 4.1 <Cenário A — ex.: criar / carregar>
+
+- **Entrada:** <de onde o usuário vem>
+- **Comportamento:** <passo a passo; loading / vazio / erro>
+- **Sucesso:** <o que o usuário vê>
+
+### 4.2 <Cenário B — ex.: editar / dados insuficientes>
+
+<mesma estrutura>
+
+### 4.N <Cenários de borda — ex.: acesso inválido, limite de plano, falha de leitura>
+
+- <…>
+
+---
+
+## 5. Contrato funcional e invariantes
+
+> Casa única de **dados + regras/segurança de negócio**. §4 e §6 referenciam, não repetem.
+
+| Conceito | Regra para o usuário / sistema |
+|----------|--------------------------------|
+| <campo ou regra> | <validação, formato, default, persistência em termos de negócio> |
+
+> Ex.: “valor em reais na digitação; gravado em centavos inteiros” — não nome de tipo Dart.
+
+**Invariantes (negócio/segurança)**
+
+- <regra que não pode ser violada; erros em linguagem de produto, sem códigos técnicos ou stack ao usuário>
+
+---
+
+## 6. Critérios de aceite (negócio)
+
+**Produto**
+
+- [ ] <observável>
+
+**UX**
+
+- [ ] <observável — espelhar §4, inclusive erros e loading>
+
+**Dados**
+
+- [ ] <integridade observável — referencie §5/D* em vez de re-derivar fontes>
+
+**Regressão de produto**
+
+- [ ] <o que já funcionava e deve continuar>
+
+---
+
+## 7. Apêndice (opcional)
+
+> Metadados leves. Omitir blocos que não agregam nesta entrega.
+
+**Riscos**
+
+| Risco | Mitigação |
+|-------|-----------|
+| <expectativa errada do usuário> | <copy, escopo, aceite — referencie D*/§ quando couber> |
+
+**Dependências:** <ID entrega — por que bloqueia ou alimenta> · <decisão externa, se houver>
+
+**Referências:** <PRD pai, regras de negócio, backlog — sem listar arquivos de código>
+
+**Histórico:** <YYYY-MM-DD — evento>
+
+---
+
+## Checklist do autor (não publicar no PRD final — opcional)
+
+- [ ] Nenhum package, classe, rota ou migration neste arquivo
+- [ ] Cada verdade tem UMA casa; demais seções referenciam por §/D-id (sem re-enumerar)
+- [ ] Todo critério de §6 tem correspondência em §4 (UX) ou §5 (dados)
+- [ ] "Fora de escopo" nomeia os adjacentes tentadores, não o complemento infinito
+- [ ] Demarcação preservada: `---`, `**Label:**`, `### N.x`, headers de tabela, grupos de aceite

package/plugins/atlas-workflow-orchestrator/templates/STATE_FILE_SCHEMA.md

@@ -0,0 +1,32 @@
+# State File Schema
+
+Boundary canônico executor → validator.
+
+Path:
+
+```text
+.atlas/state/<run_id>/<slice>.json
+```
+
+Schema mínimo:
+
+```json
+{
+  "run_id": "string (uuid ou slug)",
+  "slice": "string (ex.: 'A', 'B', 'C')",
+  "tasks": ["T01", "T02"],
+  "files_changed": ["packages/foo.js"],
+  "diff_stat": "N files, +X -Y",
+  "plan_path": ".atlas/plans/<id>.plan.md",
+  "boundary_refs": ["§2.I3", "§5.T11"],
+  "executed_at": "ISO8601",
+  "executor_skill": "atlas-plan-execute"
+}
+```
+
+Regras:
+
+- `run_id`, `slice`, `tasks`, `files_changed`, `diff_stat`, `plan_path`, `boundary_refs`, `executed_at` e `executor_skill` são obrigatórios.
+- `files_changed` contém paths relativos ao repositório consumidor.
+- `boundary_refs` aponta para invariantes, contratos ou tasks do plano que delimitam a validação.
+- O arquivo é uma projeção de boundary para o validator; estado de run continua tendo `atlas_run_state` como fonte primária quando MCP estiver disponível.