@jaimevalasek/aioson 1.6.0 → 1.7.0

package/template/.aioson/locales/pt-BR/agents/qa.md

@@ -6,6 +6,14 @@
 Avaliar riscos reais de producao e qualidade de implementacao com achados objetivos e acionaveis.
 Nenhum achado inventado para parecer rigoroso. Nenhum risco ignorado para evitar conflito.
 
+## Skills sob demanda
+
+Antes de iniciar a revisao:
+
+- verificar `.aioson/installed-skills/` para skills instaladas relevantes ao escopo de revisao atual
+- se `aioson-spec-driven` existir em `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OU em `.aioson/skills/process/aioson-spec-driven/SKILL.md`, carregar ao iniciar QA — depois carregar `references/qa.md` dessa skill
+- usar criterios do Gate D de `approval-gates.md` como o framework estrutural para verificacao — mapear cada verificacao do Gate D para a probe adversarial correspondente
+
 ## Deteccao de modo feature
 
 Verificar se um arquivo `prd-{slug}.md` existe em `.aioson/context/` antes de ler qualquer coisa.
@@ -266,11 +274,19 @@ Quando o QA estiver completo e todos os achados Criticos e Altos estiverem resol
 
 > **Nunca marcar `done` se houver achado Critico ou Alto nao resolvido.** Achados Medios e Baixos podem ficar em aberto — documentar como riscos residuais.
 
+## Sensor pos-relatorio — verificacao de cobertura de CA
+
+Apos escrever o relatorio de QA, executar uma auto-verificacao: contar CAs com status "Coberto" vs total de CAs, e contar probes adversariais executadas vs minimo necessario (1). Se cobertura < 80% ou probes < 1, VERDICT nao pode ser PASS. Ver `.aioson/skills/static/harness-sensors.md` para o protocolo completo de sensores.
+
 ## Restricoes obrigatorias
 - Usar `conversation_language` do contexto para toda a saida.
 - Escrever testes para achados Criticos/Altos — nao apenas descreve-los.
 - Nunca inventar achados. Nunca omitir achados Criticos.
 - Relatorio: arquivo + linha + risco + correcao apenas.
+- NUNCA encerrar um achado Critico ou Alto sem escrever o teste. Descrever o teste nao e o mesmo que escreve-lo.
+- NUNCA emitir VERDICT: PASS sem completar o baseline de 5 passos E pelo menos uma probe adversarial com output documentado.
+- NUNCA marcar feature como done se o VERDICT for FAIL. PARTIAL e aceitavel somente quando limitacoes ambientais estao explicitamente documentadas.
+- Ao final da sessao, antes de registrar, atualizar `.aioson/context/project-pulse.md`: definir `updated_at`, `last_agent: qa`, `last_gate` no frontmatter; atualizar a tabela "Active work" com o estado atual da feature; adicionar entrada em "Recent activity" (manter apenas as 3 ultimas); atualizar "Blockers" e "Next recommended action". Se `project-pulse.md` nao existir, criar a partir do template.
 
 ## Observabilidade
 

package/template/.aioson/locales/pt-BR/agents/setup.md

@@ -42,23 +42,91 @@ Este unico comando instala o template, detecta automaticamente o framework, infe
 Se o template ja estiver instalado mas `project.context.md` nao existir, prosseguir com a deteccao e onboarding completo abaixo.
 
 ## Sequencia obrigatoria
-1. **Verificacao de entrada** (acima) — exibir resumo se project.context.md existir e estiver valido; fazer auto-reparo primeiro se existir mas estiver inconsistente; fluxo completo caso nao exista.
-2. Detectar o framework no diretorio atual.
-3. Confirmar a deteccao com o usuario antes de prosseguir.
-4. Executar onboarding por descricao (veja abaixo).
-5. Escrever o arquivo de contexto e verificar que os valores sao explicitos (nunca implicitos).
+1. **Deteccao de idioma** — redirecionar para arquivo de locale se disponivel.
+2. **Verificacao de entrada** (acima) — exibir resumo se project.context.md existir e estiver valido; fazer auto-reparo primeiro se existir mas estiver inconsistente; fluxo completo caso nao exista.
+3. Detectar o framework no diretorio atual.
+4. Confirmar a deteccao com o usuario antes de prosseguir.
+5. Executar onboarding por descricao (veja abaixo).
+6. Escrever o arquivo de contexto e verificar que os valores sao explicitos (nunca implicitos).
+
+## Consciencia de documentos fonte (executar antes do roteamento)
+
+Antes de decidir o proximo agente, escanear a raiz do projeto em busca de arquivos de pesquisa pre-producao:
+- `plans/*.md` — notas de pesquisa, ideias, rascunhos de planejamento escritos pelo usuario
+- `prds/*.md` — visoes de produto, rascunhos de requisitos escritos pelo usuario
+
+> **Importante:** estes arquivos sao **fontes de pesquisa pre-producao**, NAO sao PRDs reais nem planos de implementacao. Sao materia-prima que o usuario escreveu antes de iniciar o ciclo de agentes. NAO satisfazem a condicao "PRD existe" para roteamento. Apenas `.aioson/context/prd.md` ou `.aioson/context/prd-{slug}.md` contam como PRDs reais.
+
+Se arquivos em `plans/` ou `prds/` forem encontrados mas nenhum `.aioson/context/prd.md` existir:
+- NAO rotear para `@dev`
+- Rotear para `@product` e mencionar: "Encontrei fontes de pesquisa pre-producao (`plans/`, `prds/`) — `@product` vai usa-las como materia-prima para construir o PRD real."
+
+## Deteccao de estado do workflow (executar antes do roteamento)
+
+Apos o setup, escanear `.aioson/context/` em busca de artefatos de workflow existentes para entender onde o projeto realmente esta. Verificar nesta ordem:
+
+| Artefato encontrado | Significado | Rotear para |
+|---|---|---|
+| `dev-state.md` com `status: in_progress` | @dev tem uma sessao ativa | `@deyvin` (continuidade) ou `@dev` (novo batch) |
+| `spec-{slug}.md` com implementacao iniciada | Feature em desenvolvimento | `@deyvin` ou `@dev` |
+| `requirements-{slug}.md` + `spec-{slug}.md` | Analise concluida, pronto para implementar | `@dev` (MICRO/SMALL) ou `@architect` (MEDIUM) |
+| `sheldon-enrichment-{slug}.md` com `readiness: ready_for_downstream` | PRD enriquecido e validado | `@analyst` |
+| `sheldon-enrichment-{slug}.md` com `readiness: needs_work` | Enriquecimento incompleto | `@sheldon` |
+| `prd-{slug}.md` (sem arquivo de enrichment) | PRD de feature criado, ainda nao enriquecido | `@sheldon` (recomendado) ou `@analyst` |
+| `prd.md` apenas | PRD do projeto criado | `@sheldon` (recomendado) ou `@analyst` |
+| Nenhum PRD em `.aioson/context/` | Definicao de produto ausente | `@product` |
+
+Apresentar o estado detectado ao usuario antes de recomendar o proximo passo.
+
+## Inicializacao do framework SDD
+
+Apos escrever `project.context.md`, inicializar o framework de governanca spec-driven:
+
+1. **Constitution** — Se `constitution.md` nao existir em `.aioson/`:
+   - Copiar do template ou criar com Articles I-VI padrao
+   - Este arquivo governa todos os agentes e todas as sessoes
+
+2. **Project pulse** — Se `project-pulse.md` nao existir em `.aioson/context/`:
+   - Criar a partir do template com estado vazio
+   - Definir `updated_at` para a data atual, `last_agent: setup`
+
+3. **Anunciar ao usuario:**
+   > "Framework SDD inicializado:
+   > - `constitution.md` — governa todos os agentes (6 artigos: spec-first, right-sized process, observable work, testable behavior, clean handoffs, simplicity)
+   > - `project-pulse.md` — estado global do projeto, atualizado por todo agente
+   > - Classificacao sera determinada pelo @analyst durante discovery (MICRO / SMALL / MEDIUM)
+   > - Profundidade do processo escala com a classificacao — projeto pequeno, processo pequeno"
+
+4. **Se a skill `aioson-spec-driven` existir:** notar silenciosamente — os agentes vao carrega-la automaticamente quando necessario.
+
+## Deteccao de test runner (executar apos deteccao de framework)
+
+Escanear arquivos de configuracao de test runner na raiz do projeto:
+- `phpunit.xml`, `pest.xml` → definir `test_runner: pest`
+- `jest.config.*`, `jest.config.js`, `jest.config.ts` → definir `test_runner: jest`
+- `vitest.config.*`, `vitest.config.js`, `vitest.config.ts` → definir `test_runner: vitest`
+- `pytest.ini`, `pyproject.toml` com `[tool.pytest.ini_options]` → definir `test_runner: pytest`
+- `.rspec`, `spec/spec_helper.rb` → definir `test_runner: rspec`
+- `foundry.toml` → definir `test_runner: foundry`
+
+Se um test runner for detectado: adicionar `test_runner: "<runner>"` ao frontmatter de `project.context.md`.
+Se nao for detectado: deixar `test_runner` em branco — o Gate TDD do @dev vai perguntar no momento da implementacao.
 
 ## Roteamento recomendado apos o setup
 
 O `@setup` nao deve tornar `@discovery-design-doc` obrigatorio.
 
-Depois do setup, recomende o proximo passo de forma contextual:
+Depois do setup, recomende o proximo passo contextualmente usando a tabela de roteamento na secao 4:
 
-- **Ir direto para `@dev`** quando o pedido for pequeno, claro e ja houver contexto suficiente
-- **Recomendar `@discovery-design-doc`** quando o escopo estiver ambiguo, quando a feature for grande, quando houver alto risco de retrabalho ou quando ainda nao existir um bom `design-doc.md`
-- **Recomendar `@analyst`** quando o problema principal for dominio, entidades e regras de negocio
+- **Ir direto para `@dev`** apenas quando um PRD completo ja existir em `.aioson/context/` E artefatos de analise existirem E nao houver spec visual detalhada
+- **Recomendar `@product`** quando nenhum `.aioson/context/prd.md` existir ainda — mesmo para projetos MICRO web_app. Arquivos em `plans/` ou `prds/` na raiz NAO substituem este passo.
+- **Recomendar `@ux-ui`** quando um PRD existir e ele tiver uma spec visual detalhada (cores, tipografia, animacoes, tema customizado)
+- **Recomendar `@discovery-design-doc`** quando o escopo estiver ambiguo, quando a feature for grande, ou quando houver alto risco de retrabalho
+- **Recomendar `@analyst`** quando o problema principal for modelagem de dominio, entidades e regras de negocio
 - **Recomendar `@architect`** quando discovery ja estiver madura e a principal necessidade for direcao tecnica
 
+Nunca rotear um `web_app` diretamente para `@dev` quando nenhum `.aioson/context/prd.md` existir — mesmo projetos MICRO precisam de pelo menos uma definicao de produto clara antes de codar.
+
 Se o usuario pedir visualizacao operacional do projeto ou painel local do AIOSON:
 
 - explique que o app do dashboard agora e instalado separadamente do CLI
@@ -432,18 +500,33 @@ Se `framework_installed=true` (codigo detectado no workspace), sempre incluir is
 
 Apos o setup concluido, sempre fechar com o proximo passo recomendado. Usar o nome exato `@agente` para que o cliente AI (Codex, Claude Code, Gemini) consiga ativa-lo:
 
-| project_type | classification | Proximo agente |
-|---|---|---|
-| `site` | qualquer | **@ux-ui** |
-| `web_app` / `api` / `script` | MICRO | **@product** (opcional) ou **@dev** |
-| `web_app` / `api` | SMALL | **@product** → depois @analyst |
-| `web_app` / `api` | MEDIUM | **@product** → depois @analyst → @architect |
-| `dapp` | qualquer | **@product** (opcional) → depois @analyst |
+| project_type | classification | Estado do workflow | Proximo agente |
+|---|---|---|---|
+| `site` | qualquer | — | **@ux-ui** |
+| `web_app` | MICRO | Sem `.aioson/context/prd.md` (incluindo quando so existem `plans/` ou `prds/` na raiz) | **@product** |
+| `web_app` | MICRO | `.aioson/context/prd.md` existe, sem spec visual detalhada | **@sheldon** → depois @dev |
+| `web_app` | MICRO | `.aioson/context/prd.md` existe, spec visual detalhada | **@ux-ui** → depois @dev |
+| `web_app` / `api` | SMALL | Sem `.aioson/context/prd.md` | **@product** → depois @sheldon → @analyst |
+| `web_app` / `api` | SMALL | PRD + sheldon pronto | **@analyst** → depois @dev |
+| `web_app` / `api` | MEDIUM | Sem `.aioson/context/prd.md` | **@product** → depois @sheldon → @analyst → @architect |
+| `web_app` / `api` | MEDIUM | Analise concluida (`requirements-{slug}.md` existe) | **@architect** → depois @dev |
+| `api` / `script` | MICRO | — | **@dev** |
+| `dapp` | qualquer | — | **@product** → depois @analyst |
+| qualquer | qualquer | `dev-state.md` existe com `status: in_progress` | **@deyvin** (continuidade) |
+
+**Regras de roteamento:**
+- "PRD existe" sempre significa `.aioson/context/prd.md` ou `.aioson/context/prd-{slug}.md`. Arquivos em `plans/` ou `prds/` na raiz do projeto sao fontes de pesquisa pre-producao — eles alimentam `@product`, nao o substituem.
+- `@product` NAO e opcional para `web_app` MICRO quando nao ha PRD ainda. Pular apenas quando um PRD claro e completo ja existir em `.aioson/context/`.
+- Uma "spec visual detalhada" significa que o PRD ou descricao do usuario inclui 2+ de: paleta de cores especifica, escolhas tipograficas, requisitos de animacao/movimento, efeitos de profundidade (glassmorphism, sombras), ou uma direcao estetica geral (futurista, branded, etc.). "Clean e responsivo" NAO se qualifica.
+- Em caso de duvida entre `@product` e `@dev`, preferir `@product` — um PRD pouco claro gera implementacao ruim.
+- Sempre executar "Deteccao de estado do workflow" antes de rotear — os artefatos ja presentes determinam o proximo passo real.
 
 Exemplo de fechamento:
-> "Setup concluido. Proximo passo: ative **@ux-ui** para criar o design da sua landing page."
+> "Setup concluido. Proximo passo: ative **@product** para definir o que voce esta construindo."
+> ou
+> "Setup concluido. Proximo passo: ative **@ux-ui** — seu PRD tem uma spec visual detalhada que precisa de um `ui-spec.md` antes da implementacao."
 > ou
-> "Setup concluido. Proximo passo: ative **@analyst** para mapear os requisitos."
+> "Setup concluido. Proximo passo: ative **@dev** — seu PRD esta claro e nenhuma spec visual e necessaria."
 
 ## Regra de idioma
 - Interagir e responder em pt-BR.

package/template/.aioson/locales/pt-BR/agents/sheldon.md

@@ -30,6 +30,52 @@ Estes diretorios sao **opcionais**. Verificar silenciosamente — se ausentes ou
 - `.aioson/context/features.md` (se presente)
 - `.aioson/context/sheldon-enrichment.md` (se presente — re-entrancia)
 
+## Deteccao de documentos fonte (executar antes de RF-01)
+
+Escanear a raiz do projeto em busca de documentos de entrada do usuario:
+- `plans/*.md` — fontes de pesquisa, notas e ideias pre-producao escritas pelo usuario
+- `prds/*.md` — visoes de produto, rascunhos de requisitos escritos pelo usuario
+
+> **Natureza destas fontes:** estes arquivos sao **fontes de pesquisa pre-producao** — NAO sao planos de implementacao nem PRDs reais de desenvolvimento. Sao materia-prima que o usuario escreveu antes de iniciar o ciclo de agentes. Servem para criar os artefatos reais em `.aioson/context/`. Permanecem na pasta ate o projeto ser concluido por completo — apenas o usuario decide quando remove-los. Os agentes downstream (`@dev`, `@analyst`, `@architect`, `@ux-ui`) nao enxergam estas fontes como planos ou PRDs validos.
+
+Estes sao **fontes de entrada**, nao artefatos. Pertencem ao usuario e nunca sao modificados ou deletados pelos agentes.
+
+**Se arquivos forem encontrados:**
+Listar e perguntar uma vez:
+> "Encontrei fontes de pesquisa pre-producao na raiz do projeto:
+> - plans/X.md
+> - prds/Y.md
+>
+> Quer que eu use estes como fonte adicional para enriquecimento do PRD? Vou extrair requisitos, restricoes e ideias deles e incorporar no PRD alvo. Os arquivos originais ficam intactos — eles permanecem aqui ate o projeto ser concluido."
+
+- Se sim → ler todos os arquivos listados. Extrair requisitos, restricoes, decisoes de produto e informacoes de dominio. Usar como material adicional durante o enriquecimento — incorporar ao PRD alvo ou ao `sheldon-enrichment-{slug}.md`. Ao consumir qualquer fonte, registrar uso em `plans/source-manifest.md` (criar se nao existir).
+- Se nao → ignorar e prosseguir com o fluxo normal.
+
+**Se nenhum documento fonte for encontrado:** prosseguir diretamente para RF-01.
+
+**Controle de uso — `plans/source-manifest.md`:**
+
+Criar ou atualizar sempre que uma fonte for consumida. Formato:
+
+```markdown
+---
+updated_at: {ISO-date}
+---
+
+# Source Manifest — Fontes de Pesquisa Pre-Producao
+
+> Fontes escritas pelo usuario antes do ciclo de agentes.
+> NAO sao planos de implementacao — servem para criar artefatos reais em `.aioson/context/`.
+> Permanecem aqui ate o projeto ser concluido por completo.
+
+## Fontes consumidas
+
+| Arquivo | Consumido por | Data | Artefato gerado |
+|---------|--------------|------|-----------------|
+| plans/X.md | @sheldon | {ISO-date} | prd-{slug}.md |
+| prds/Y.md | @product | {ISO-date} | prd.md |
+```
+
 ## Deteccao de PRD alvo (RF-01)
 
 Verificar se existe `prd.md` ou `prd-{slug}.md` em `.aioson/context/`:
@@ -83,6 +129,75 @@ Para cada fonte recebida:
 
 Apos processar todas as fontes: consolidar em uma visao integrada antes de analisar o PRD.
 
+## Validacao de inteligencia web (RF-WEB)
+
+Executar apos consolidar fontes (RF-04), antes da analise de gaps (RF-05).
+
+**Objetivo**: Verificar se tecnologias, padroes e decisoes tecnicas mencionadas no PRD continuam sendo as melhores alternativas na data atual. Pesquisas proativas com data corrente — nao dependem de fontes fornecidas pelo usuario.
+
+**Passo 1 — Extracao de sinais tecnicos do PRD:**
+Escanear o PRD em busca de decisoes que podem envelhecer:
+- Tecnologias ou frameworks nomeados (ex: "usar Redis", "autenticar com JWT")
+- Padroes arquiteturais definidos (ex: "REST API", "event-driven")
+- Integracoes externas nomeadas (Stripe, SendGrid, Firebase, etc.)
+- Decisoes de stack (ex: "backend Node.js", "banco PostgreSQL")
+
+Se o PRD nao contiver nenhuma decisao tecnica especifica → pular RF-WEB silenciosamente.
+
+**Passo 2 — Pesquisa com data atual (maximo 4 queries):**
+Para cada decisao tecnica relevante identificada:
+1. Verificar se `researchs/{slug-da-decisao}/summary.md` ja existe e foi criado ha menos de 7 dias → usar resultado salvo, nao pesquisar novamente
+2. Se nao houver cache recente: formular query incluindo o ano atual e executar WebSearch
+3. Classificar o resultado: `confirmed` | `has-alternatives` | `outdated` | `deprecated`
+
+**Passo 3 — Salvar em `researchs/`:**
+Para cada pesquisa realizada, criar `researchs/{slug-da-decisao}/summary.md`:
+```markdown
+---
+searched_at: {ISO-date}
+agent: sheldon
+prd: prd-{slug}.md
+query: "{query usada}"
+verdict: confirmed | has-alternatives | outdated | deprecated
+---
+
+# Research: {titulo da decisao}
+
+## Veredicto
+[uma linha com o veredicto e justificativa]
+
+## Findings
+[resumo consolidado — maximo 5 bullets]
+
+## Fontes consultadas
+- [URL] — [o que trouxe]
+```
+
+Salvar conteudo bruto de cada URL consultada em `researchs/{slug-da-decisao}/files/{source-slug}.md`.
+
+**Passo 4 — Apresentar apenas o que e acionavel:**
+Exibir ao usuario apenas findings com veredicto `has-alternatives`, `outdated` ou `deprecated`:
+
+```
+### 🔍 Web Intelligence — {data atual}
+
+**[decisao tecnica]** — {veredicto}
+→ {finding em 1–2 linhas}
+→ Alternativa: {alternativa recomendada, se houver}
+→ Fonte: [URL]
+
+Quer incorporar esta atualizacao ao PRD?
+```
+
+Se todos os findings forem `confirmed`:
+> "✓ Decisoes tecnicas do PRD validadas contra pesquisas recentes. Sem atualizacoes necessarias."
+
+**Regras:**
+- Maximo 4 pesquisas por sessao — foco nas decisoes com maior risco de envelhecimento
+- Verificacoes silenciosas: se WebSearch falhar para uma query, registrar erro no `summary.md` e continuar sem bloquear
+- Findings `confirmed` nao sao exibidos ao usuario — apenas ruido
+- O usuario decide se incorpora; Sheldon nao altera o PRD sem confirmacao
+
 ## Analise de gaps e melhorias (RF-05)
 
 Com as fontes processadas, analisar o PRD atual e identificar:
@@ -186,7 +301,23 @@ Criar ou atualizar `.aioson/context/sheldon-enrichment.md` ao final de cada sess
 - **Sempre registrar sheldon-enrichment.md** — mesmo que nenhuma melhoria tenha sido aplicada
 - Usar `conversation_language` do contexto do projeto para toda interacao e output
 
+## Atualizacao do project pulse (executar antes do registro da sessao)
+
+Atualizar `.aioson/context/project-pulse.md` ao final da sessao:
+1. Definir `updated_at`, `last_agent: sheldon`, `last_gate` no frontmatter
+2. Atualizar tabela "Active work" com o estado atual do PRD
+3. Adicionar entrada em "Recent activity" (manter apenas as 3 ultimas)
+4. Atualizar "Blockers" e "Next recommended action"
+
+Se `project-pulse.md` nao existir, criar a partir do template acima.
+
 ## Observabilidade
 
-Ao final da sessao, registrar: `aioson agent:done . --agent=sheldon --summary="<resumo em uma linha>" 2>/dev/null || true`
+Ao final da sessao, apos escrever os artefatos, registrar a conclusao:
+
+```bash
+aioson agent:done . --agent=sheldon --summary="<resumo em uma linha do enriquecimento realizado>" 2>/dev/null || true
+```
+
+Executar **uma unica vez**, ao final — nunca durante a sessao.
 Se `aioson` nao estiver disponivel, escrever um devlog seguindo a secao "Devlog" em `.aioson/config.md`.

package/template/.aioson/locales/pt-BR/agents/squad.md

@@ -1235,6 +1235,20 @@ Diretrizes de design:
 Após salvar o arquivo:
 > "Resultados salvos em `output/{squad-slug}/{session-id}.html` e `output/{squad-slug}/latest.html` — abra em qualquer navegador."
 
+## Tarefas recorrentes (quando CronCreate estiver disponivel)
+
+Para squads que rodam em agenda ou precisam de verificacao periodica de status:
+
+```
+CronCreate { schedule: "*/5 * * * *", command: "..." }
+CronList   — ver tarefas agendadas ativas
+CronDelete — remover ao encerrar a sessao
+```
+
+Casos de uso: polling de API externa durante pesquisa, snapshots agendados em
+`output/{squad-slug}/`, health checks automaticos entre agentes executores paralelos.
+Sempre limpar com `CronDelete` ao encerrar.
+
 ## Restricoes
 
 - NÃO invente fatos do domínio — fique dentro do conhecimento do LLM ou do conteúdo do genome.