nexus-core-v3 3.0.0

package/tasks/README.md

@@ -0,0 +1,72 @@
+# NEXUS Tasks — a camada procedural
+
+Se o DNA do agente (`agents/`) é **quem** o agente é, a task é **o que ele faz, passo a passo**. Uma
+task é um workflow executável: um agente lê a task e a executa exatamente como escrita. Cada `owns:`
+no DNA de um agente aponta para uma task aqui.
+
+> **Uma task validada é lei.** Ela deve ser executada conforme configurada, com todas as suas
+> pré-condições respeitadas, independente de quem a executa (agente, worker, clone ou humano). As
+> tasks são o conhecimento procedural — o que faz o output sair bom **de forma repetível**.
+
+## Formato canônico
+
+Frontmatter YAML (metadados estruturados) + corpo Markdown (os passos executáveis).
+
+```markdown
+---
+id: dev-develop-story        # kebab-case, único. Casa com o `owns:` do agente dono.
+agent: dev                   # id do agente dono (governa a autoridade)
+title: Implementar uma story
+inputs: [story]              # o que a task precisa para começar
+outputs: [código, testes, File List atualizada]  # o que ela produz
+elicit: false                # true = exige interação humana num ponto (não pode ser pulado)
+modes: [interactive, yolo]   # modos de execução suportados (default: [interactive])
+---
+
+# {title}
+
+**Objetivo:** uma frase — o resultado que esta task entrega.
+
+**Pré-condições:** o que tem que ser verdade antes de começar (senão, pare e reporte).
+
+## Passos
+1. Passo concreto e verificável.
+2. ...
+
+## Critério de pronto (DoD)
+- [ ] Condições objetivas que separam "feito" de "feito direito".
+
+## Falha / recuperação
+- O que fazer quando um passo falha (rollback, escalar, HALT).
+```
+
+## Regras
+
+- **elicit: true é sagrado.** Uma task com ponto de elicitação NÃO pode ser pulada "por eficiência" —
+  exige a interação real do usuário no formato especificado.
+- **Autoridade vem do agente dono.** Uma task de `agent: dev` não faz `git push` (isso é do devops),
+  porque o Dex não tem essa autoridade. A task herda as guardas do DNA do dono.
+- **Sem invenção (Constituição Art. IV).** Os passos produzem artefatos que rastreiam a um
+  objetivo/story/spec — não inventam escopo.
+- **NEXUS-nativo.** Agentes são os do roster (`nexus-master`, `dev`, `qa`…); comandos são `nexus run`
+  / `nexus party`. Nada de frameworks externos.
+- **Onde as coisas moram:**
+  - `docs/{tipo}/` — artefatos PRODUZIDOS (stories em `docs/stories/`, PRD em `docs/prd/`, arquitetura
+    em `docs/architecture/`, epics, qa, specs, research, design-system, data-models). É o trabalho.
+  - `.nexus/` — estado de RUNTIME do framework (handoffs, mapas de sync, cache, registry, logs). Não
+    é entregável; é a memória operacional.
+  - `templates/` e `checklists/` — esqueletos e critérios que as tasks consomem.
+
+## Tipos de task (por forma)
+
+| Tipo | Forma | Exemplos |
+|---|---|---|
+| **Execução** | passos que produzem um artefato/código | `dev-develop-story`, `create-next-story`, `create-schema` |
+| **Gate** | passos que avaliam e emitem um veredito | `qa-gate`, `validate-next-story`, `pre-push-quality-gate` |
+| **Orquestração** | passos que decompõem e delegam (tocam o motor) | `orchestrate`, `deliberate`, `route` |
+| **Checklist** | critérios a verificar item a item | `execute-checklist`, `accessibility-wcag-checklist` |
+
+## Templates e checklists
+
+`templates/` guarda os esqueletos de documento (story, PRD, arquitetura) que as tasks preenchem.
+`checklists/` guarda os critérios de validação (DoD, prontidão de story) que os gates rodam.

package/tasks/accessibility-wcag-checklist.md

@@ -0,0 +1,69 @@
+---
+id: accessibility-wcag-checklist
+agent: ux-design-expert
+title: Auditoria de acessibilidade WCAG (AA/AAA)
+inputs: [componente-ou-tela, nivel-wcag]
+outputs: [veredito PASS/FAIL, lista de violações, relatório de a11y]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Auditoria de acessibilidade WCAG (AA/AAA)
+
+**Objetivo:** auditar um componente ou tela contra os critérios WCAG e emitir um veredito objetivo —
+WCAG AA é o piso inegociável; AAA quando a story exigir. Reprovado bloqueia a entrega.
+
+**Pré-condições:**
+- O alvo (componente ou tela) está renderizável/inspecionável. Se não roda, **pare** — não audito o
+  que não consigo observar.
+- O nível-alvo está definido (AA por padrão; AAA só se a story/spec pedir). Sem definição, assumo AA.
+
+## Passos — checklist (verifico item a item)
+
+1. **Contraste de cor**
+   - [ ] Texto normal ≥ 4.5:1 (AA) / ≥ 7:1 (AAA)
+   - [ ] Texto grande (≥ 18.66px bold ou 24px) ≥ 3:1 (AA) / ≥ 4.5:1 (AAA)
+   - [ ] Componentes de UI e estados (borda, foco, ícone informativo) ≥ 3:1
+2. **Navegação por teclado**
+   - [ ] Todo elemento interativo é alcançável por `Tab` na ordem lógica
+   - [ ] Nada vira "armadilha de teclado" (dá pra entrar e sair)
+   - [ ] Ações de mouse têm equivalente por teclado (`Enter`/`Space`/setas)
+3. **Foco visível**
+   - [ ] Indicador de foco visível e com contraste suficiente em cada elemento focável
+   - [ ] Ordem de foco segue a ordem visual/lógica
+4. **Semântica e estrutura**
+   - [ ] HTML semântico ou `role` correto (botão é botão, não `div` clicável)
+   - [ ] Hierarquia de headings coerente; landmarks onde fizer sentido
+   - [ ] Estados expostos via ARIA quando necessário (`aria-expanded`, `aria-checked`, `aria-invalid`)
+5. **Texto alternativo e rótulos**
+   - [ ] Imagens informativas têm `alt` descritivo; decorativas têm `alt=""`
+   - [ ] Todo campo de formulário tem `label` associado
+   - [ ] Ícone-só-clicável tem `aria-label`
+6. **Conteúdo e movimento**
+   - [ ] Informação não depende só de cor (estado/erro tem texto ou ícone também)
+   - [ ] Animação/auto-play respeita `prefers-reduced-motion`
+   - [ ] Mensagens de erro são programaticamente associadas e anunciadas
+7. **Emito o veredito** consolidando os itens:
+   - **PASS** — todos os itens do nível-alvo verdes.
+   - **FAIL** — qualquer item do nível-alvo reprovado, com a lista exata de violações e onde corrigir.
+8. **Registro o relatório de a11y** (itens, veredito, violações) e o anexo à story. Se FAIL, **bloqueio
+   a entrega** e devolvo a correção ao dono do componente (a mim no `*build`/`*extend`, ou ao @dev se
+   for integração na app).
+
+## Critério de pronto (DoD)
+
+- [ ] Todos os 6 grupos do checklist avaliados item a item
+- [ ] Veredito explícito: PASS ou FAIL
+- [ ] Se FAIL, lista de violações com localização e correção sugerida
+- [ ] Relatório de a11y anexado à story
+- [ ] Entrega bloqueada enquanto houver violação de nível AA aberta
+
+## Falha / recuperação
+
+- **Item reprova no nível AA** → veredito FAIL automático; a11y AA é piso, não negocio. Bloqueio a
+  entrega e devolvo para correção.
+- **Não consigo medir um critério** (ex.: contraste de estado dinâmico) → registro como "não
+  verificável", trato como risco aberto e não declaro PASS no escuro.
+- **Violação exige mudança de arquitetura/stack** (ex.: trocar lib inacessível) → reporto e escalo para
+  @architect; não decido stack sozinha.
+- **Correção está fora do design system (integração na app)** → delego ao @dev; eu audito, ele integra.

package/tasks/advanced-elicitation.md

@@ -0,0 +1,42 @@
+---
+id: advanced-elicitation
+agent: analyst
+title: Elicitação avançada — apertar a pergunta
+inputs: [objetivo / artefato ou afirmação a refinar]
+outputs: [pergunta/escopo afiado, premissas explicitadas, decisão destravada]
+elicit: true
+modes: [interactive]
+---
+
+# Elicitação avançada — apertar a pergunta
+
+**Objetivo:** rodar uma sondagem estruturada que transforma um briefing vago numa pergunta nítida — descobrindo premissas, restrições e a decisão real por trás do pedido, perguntando "por quê" até o fundo.
+
+**Pré-condições:**
+- Há um pedido, artefato ou afirmação para refinar. Esta task é o instrumento que outras tasks chamam quando o objetivo está nebuloso demais para prosseguir.
+- O usuário está disponível para responder — elicitação é interação real, não pode ser simulada.
+
+## Passos
+
+1. **Espelho o pedido.** Reformulo o que entendi em uma frase e peço confirmação. **(ponto de elicitação — exige resposta real do usuário)**
+2. **Ofereço um menu de técnicas** adequadas ao caso e aplico a escolhida (ex.: 5 Porquês, First Principles, Pre-mortem, Red Team, Socrático, Análise de Premissas). Anuncio qual estou usando.
+3. **Sondo camada por camada.** Pergunto "por quê" repetidamente até a causa-raiz/decisão real aparecer — a primeira resposta raramente é o fundo. Uma pergunta por vez, sem despejar tudo de uma vez.
+4. **Explicito as premissas.** Listo as suposições implícitas no pedido e marco quais são fatos verificáveis e quais são hipóteses a validar.
+5. **Mapeio restrições e critério de sucesso.** O que limita a solução (CON-*), e o que conta como "resolvido". Confirmo com o usuário.
+6. **Reescrevo a pergunta afiada.** Entrego a versão nítida do objetivo, com escopo, premissas e critério — pronta para alimentar a task que chamou esta (brainstorm, pesquisa, brief, etc.).
+7. **Devolvo o controle.** Roteio o objetivo refinado de volta à task/agente de origem.
+
+## Critério de pronto (DoD)
+
+- [ ] Pedido reformulado e confirmado com o usuário (elicitação cumprida)
+- [ ] Técnica nomeada aplicada e registrada
+- [ ] Sondagem chegou à decisão/causa-raiz real (não parou na 1ª resposta)
+- [ ] Premissas explicitadas e separadas em fatos vs. hipóteses
+- [ ] Restrições e critério de sucesso mapeados
+- [ ] Objetivo afiado entregue e roteado de volta à origem
+
+## Falha / recuperação
+
+- **Usuário não responde / indisponível** → como elicit é sagrado, não posso simular as respostas; reporto que a task precisa da interação e pauso em vez de inventar o escopo.
+- **Cada camada abre mais perguntas (sem convergência)** → marco um teto de profundidade, registro as questões em aberto e entrego a melhor versão possível do objetivo, sinalizando o que falta.
+- **O pedido se revela fora do meu escopo** (decisão de produto/arquitetura) → afino a pergunta e delego ao dono (@pm, @architect, @sm) em vez de decidir por eles.

package/tasks/analyze-performance.md

@@ -0,0 +1,54 @@
+---
+id: analyze-performance
+agent: data-engineer
+title: Analisar performance do banco
+inputs: [type, query, story]
+outputs: [diagnóstico com explain plan/métricas, recomendações justificadas]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Analisar performance do banco
+
+**Objetivo:** diagnosticar performance por evidência — explain plan e métricas reais — no tipo pedido
+(`query`, `hotpaths` ou `interactive`), e recomendar mudanças justificadas, nunca por palpite.
+
+**Pré-condições:**
+- O `type` é `query` (uma query específica, exige `query`), `hotpaths` (queries mais custosas do
+  workload) ou `interactive` (exploração guiada).
+- Para `query`, a query foi fornecida. Para `hotpaths`, há estatísticas disponíveis
+  (`pg_stat_statements` ou equivalente). Sem evidência, **pare** — não otimizo no escuro.
+
+## Passos
+
+1. **Capture a linha de base medida.** `query`: `EXPLAIN (ANALYZE, BUFFERS)` da query alvo. `hotpaths`:
+   liste do `pg_stat_statements` as queries por tempo total/médio e por chamadas. Medição antes de
+   qualquer hipótese.
+2. **Leia o plano:** seq scans em tabela grande, sorts/hashes em disco, estimativas de linhas longe do
+   real (estatísticas desatualizadas), loops aninhados caros, FK filtrada sem índice de suporte.
+3. **Forme a hipótese de causa** ligada à evidência do plano — não à intuição. Ex.: "seq scan de 2M
+   linhas no filtro `user_id` → falta índice".
+4. **Recomende a mudança mínima que o plano justifica:** índice (com a coluna/ordem exata), reescrita
+   da query, `ANALYZE` para atualizar estatísticas, ou desnormalização documentada. Um índice sem
+   query que o justifique é peso morto — não recomendo.
+5. **Estime o ganho e o custo:** o índice acelera leitura, mas pesa na escrita e em espaço. Registro o
+   trade-off para a decisão ser informada.
+6. **Emita o diagnóstico** com plano antes, causa, recomendação e ganho esperado. Aplicar índice =
+   migration (snapshot → dry-run → apply) — fora desta task de análise.
+
+## Critério de pronto (DoD)
+
+- [ ] Linha de base medida (explain plan / métricas reais), não estimada
+- [ ] Causa raiz ligada à evidência do plano
+- [ ] Recomendação mínima e justificada, com trade-off escrita/espaço explícito
+- [ ] Cada índice proposto serve a uma query real
+- [ ] Diagnóstico emitido; nenhuma mudança aplicada nesta task
+
+## Falha / recuperação
+
+- **Sem `pg_stat_statements` (hotpaths)** → sinalizo a dependência e ofereço habilitá-la (via @devops
+  se exigir config de infra) antes de prosseguir.
+- **Plano não revela causa clara** → coleto mais evidência (estatísticas, distribuição de dados) antes
+  de recomendar; não chuto índice.
+- **Recomendação vira migration** → entrego o plano; aplicação segue snapshot → dry-run → apply, e o
+  push é do @devops.

package/tasks/analyze-project-structure.md

@@ -0,0 +1,59 @@
+---
+id: analyze-project-structure
+agent: architect
+title: Analisar a estrutura do projeto para uma nova feature
+inputs: [story]
+outputs: [mapa de estrutura, pontos de integração, recomendação REUSE/ADAPT/CREATE]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Analisar a estrutura do projeto para uma nova feature
+
+**Objetivo:** mapear onde uma feature da story vai morar dentro da estrutura existente — quais módulos
+ela toca, o que reusa e onde encaixa — antes que uma linha seja escrita, para que o @dev implemente
+sem reinventar o que já existe.
+
+**Pré-condições:**
+- Existe uma story (ou spec) que descreve a feature. Sem ela, **pare** e elicite o escopo — não
+  analiso estrutura para um alvo que não rastreia a um pedido.
+- O repositório está acessível e legível. Se for um codebase desconhecido, prefiro rodar primeiro a
+  task `document-project` para ter o mapa antes de analisar o encaixe.
+
+## Passos
+
+1. **Leia a story COMPLETA** — ACs, notas, restrições. Extraio o que a feature precisa tocar:
+   camadas (frontend/backend/dados/infra), entidades de domínio e contratos de API.
+2. **Mapeie a árvore relevante** (`Glob`/`Read`) — não o repositório inteiro, só os diretórios que a
+   feature habita. Identifico a convenção de organização (por camada, por feature, por domínio) e a
+   sigo; não imponho uma estrutura nova sem justificativa.
+3. **Liste os pontos de integração.** Para cada camada que a feature toca, anoto o ponto exato de
+   encaixe: rota/handler, serviço, modelo de dados, componente. Cada ponto vira uma fronteira com um
+   dono (banco → @data-engineer; UI → @ux-design-expert; código → @dev).
+4. **Decida REUSE > ADAPT > CREATE** para cada peça. Procuro o utilitário/componente/serviço que já
+   resolve. Se existe, REUSE. Se quase resolve, ADAPT (sem quebrar quem consome). Só CREATE quando
+   nada serve — e registro o porquê. Over-engineering é dívida desde o dia um.
+5. **Rode o teste do 10× nos pontos de integração.** Para cada encaixe, pergunto o que quebra ao
+   escalar: N+1, hot path, acoplamento que vira gargalo. Anoto o failure mode, não só o caminho feliz.
+6. **Entregue o mapa de estrutura ao @dev** — árvore relevante, pontos de integração com donos,
+   recomendação REUSE/ADAPT/CREATE por peça, e os riscos de escala. Roteio o que for de outra camada
+   ao especialista dono.
+
+## Critério de pronto (DoD)
+
+- [ ] Cada camada que a feature toca tem o ponto de integração exato identificado, com dono
+- [ ] Cada peça tem decisão explícita REUSE/ADAPT/CREATE, com justificativa para CREATE
+- [ ] Os pontos de integração têm o failure mode ao escalar anotado (teste do 10×)
+- [ ] O mapa rastreia inteiramente à story — sem feature ou módulo inventado
+- [ ] Frentes de outra camada (dados/UI/infra) foram roteadas ao especialista dono
+
+## Falha / recuperação
+
+- **A story é vaga demais para localizar o encaixe** → paro, registro a lacuna e devolvo ao @sm/@po.
+  Não chuto a estrutura de uma feature que não entendo.
+- **O codebase é desconhecido e sem documentação** → rodo `document-project` primeiro; analisar
+  encaixe sobre um mapa que não existe gera recomendação errada.
+- **A análise revela que a feature exige mudança estrutural cross-stack** → escalo para a task
+  `architect-analyze-impact` antes de recomendar o encaixe.
+- **A feature toca schema/DDL, UI ou infra** → defino a fronteira e o contrato, mas delego a
+  implementação da camada ao dono (@data-engineer, @ux-design-expert, @devops).

package/tasks/apply-qa-fixes.md

@@ -0,0 +1,57 @@
+---
+id: apply-qa-fixes
+agent: dev
+title: Aplicar o feedback de QA na implementação
+inputs: [story, gate de QA (qa.gate)]
+outputs: [código corrigido, testes, File List atualizada, status: Ready for Review]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Aplicar o feedback de QA na implementação
+
+**Objetivo:** absorver o veredito do @qa e corrigir os pontos levantados na minha implementação,
+deixando a story verde de novo — sem reescrever o que já passou e sem tocar no que não é meu.
+
+**Pré-condições:**
+- Existe um gate de QA com veredito `CONCERNS` ou `FAIL` (ou notas de review) apontando issues
+  concretas na story. Se o veredito é `PASS` sem ressalvas, **pare** — não há o que corrigir.
+- A story está em `InReview` (voltou do QA). Se está em outro status, confirmo a procedência antes
+  de mexer.
+
+## Passos
+
+1. **Leio o gate de QA** e extraio a lista de issues, cada uma com seu AC/severidade. Priorizo:
+   bloqueadores (`FAIL`) antes de ressalvas (`CONCERNS`).
+2. **Confirmo que cada issue é minha lane.** Issue de código/teste → corrijo. Issue que aponta AC
+   errado, escopo ou requisito ausente → **não conserto por conta própria**: devolvo ao @sm/@po,
+   porque AC e escopo não são meus.
+3. **Corrijo issue por issue, pelo menor caminho:**
+   a. aplico a correção mínima que resolve o ponto levantado;
+   b. escrevo/ajusto o teste que prova que a issue foi fechada;
+   c. rodo lint + os testes da área.
+4. **Atualizo a File List** com cada arquivo tocado na correção.
+5. **Rodo a regressão completa** (lint + typecheck + toda a suíte) — corrigir uma coisa não pode
+   quebrar outra. Vermelho não volta pro QA.
+6. **Atualizo Completion Notes e Change Log** descrevendo o que mudou em resposta a cada issue do
+   gate (rastreabilidade: issue → fix).
+7. **Seto Status = `Ready for Review`** e roteio de volta ao @qa. **Não** dou `git push` — a subida
+   é do @devops; faço commit local e delego.
+
+## Critério de pronto (DoD)
+
+- [ ] Toda issue de `FAIL`/`CONCERNS` da minha lane foi corrigida, cada uma com teste verde
+- [ ] Issues fora da minha lane (AC/escopo) foram devolvidas ao @sm/@po, não "consertadas"
+- [ ] Regressão completa verde: lint limpo, typecheck 0, suíte completa passando
+- [ ] File List, Completion Notes e Change Log atualizados (rastro issue → fix)
+- [ ] Status = `Ready for Review`; commit local feito, sem `git push`
+
+## Falha / recuperação
+
+- **Uma issue do gate é na verdade um problema de AC/escopo** → devolvo ao @sm/@po; não reescrevo a
+  story para "fechar" a issue.
+- **A correção de uma issue quebra outra área (regressão)** → paro, registro no Debug Log e resolvo
+  antes de devolver ao QA. Não empurro regressão conhecida.
+- **3 tentativas falhas na mesma issue** → HALT e reporto; não empilho gambiarra sobre gambiarra.
+- **O veredito do QA está ambíguo (não dá pra saber o que corrigir)** → peço esclarecimento ao @qa
+  antes de adivinhar.

package/tasks/architect-analyze-impact.md

@@ -0,0 +1,62 @@
+---
+id: architect-analyze-impact
+agent: architect
+title: Mapear o impacto cross-stack de uma mudança estrutural
+inputs: [mudança proposta]
+outputs: [mapa de impacto, módulos afetados, riscos de escala, recomendação]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Mapear o impacto cross-stack de uma mudança estrutural
+
+**Objetivo:** traçar a onda de choque de uma mudança estrutural por todas as camadas — quem depende
+do que muda, o que quebra ao escalar e qual o custo — para que a decisão seja tomada com o blast
+radius inteiro à vista, não só o ponto da edição.
+
+**Pré-condições:**
+- A mudança proposta rastreia a uma story, spec ou restrição explícita. Sem isso, **pare** e elicite
+  — não analiso impacto de uma mudança que ninguém pediu.
+- O codebase está acessível. Se for desconhecido, rodo `document-project` antes para ter o mapa de
+  dependências.
+
+## Passos
+
+1. **Defina a mudança com precisão.** O que exatamente muda: um contrato de API, um modelo de dados,
+   uma fronteira de serviço, uma dependência. Uma mudança mal delimitada produz um mapa de impacto
+   inútil.
+2. **Encontre todos os dependentes** (`Grep`/`Glob`, e code-intel se disponível). Quem importa,
+   chama ou consome o que muda. Sigo a cadeia até as folhas — um consumidor esquecido é um incidente
+   em produção.
+3. **Classifique o impacto por camada.** Para frontend, backend, dados e infra, anoto: muda /
+   precisa adaptar / fica intacto. Cada camada afetada tem um dono (banco → @data-engineer; UI →
+   @ux-design-expert; código → @dev; infra/CI → @devops).
+4. **Rode o teste do 10× na mudança.** O que quebra quando escalar com a mudança aplicada? Migração
+   de dados sob carga, breaking change de contrato, ponto único de falha novo. Anoto o failure mode,
+   não só o caminho feliz.
+5. **Estime o custo e o risco.** Esforço por camada, risco de breaking change, necessidade de
+   migração/feature-flag/rollback. Segurança e custo são camadas do design, não apêndices — entram
+   no mapa.
+6. **Emita a recomendação.** PROSSEGUIR (impacto contido, plano claro) / FRACIONAR (quebrar em passos
+   menores e seguros) / RECONSIDERAR (custo/risco maior que o ganho). Roteio cada frente afetada ao
+   dono e, se virar plano de execução, encaminho para `plan-create-implementation`.
+
+## Critério de pronto (DoD)
+
+- [ ] Todos os dependentes do que muda foram rastreados até as folhas
+- [ ] O impacto está classificado por camada (muda/adapta/intacto), cada um com dono
+- [ ] O failure mode ao escalar foi declarado para a mudança (teste do 10×)
+- [ ] Custo, risco e estratégia de migração/rollback estão no mapa
+- [ ] Há uma recomendação explícita (PROSSEGUIR/FRACIONAR/RECONSIDERAR) que rastreia ao pedido
+
+## Falha / recuperação
+
+- **A cadeia de dependentes é grande demais para mapear com confiança** → recomendo FRACIONAR a
+  mudança em passos menores e analiso cada um; não dou por seguro um blast radius que não consegui
+  fechar.
+- **A mudança exige migração de dados ou schema** → defino o contrato e o risco, mas delego o DDL e o
+  plano de migração à @data-engineer.
+- **A mudança toca CI/CD, release ou infra de deploy** → delego ao @devops; eu mapeio o impacto,
+  não executo a mudança de infra.
+- **Descubro que a mudança não rastreia a nenhum requisito** → paro e devolvo: não há No Invention que
+  justifique uma mudança estrutural órfã.

package/tasks/archive-squad.md

@@ -0,0 +1,52 @@
+---
+id: archive-squad
+agent: squad-creator
+title: Arquivar um squad que cumpriu a missão
+inputs: ['id do squad', motivo do arquivamento]
+outputs: ['squads/{id}/ movido para squads/_archive/{id}/ pelo motor', registro do desfecho no manifest]
+elicit: true
+modes: [interactive]
+---
+
+# Arquivar um squad que cumpriu a missão
+
+**Objetivo:** encerrar o ciclo de vida de um squad — missão cumprida (ou cancelada) — movendo-o
+para o arquivo com o desfecho registrado, preservando o histórico. Arquivar é destrutivo para a
+operação (o squad some do roster ativo); por isso exige confirmação explícita (Lei 1).
+
+**Pré-condições:**
+- `squads/{id}/` existe. Squad inexistente → reporte e HALT, nada a arquivar.
+- O motivo do desfecho é conhecido: `completed` (missão cumprida) ou `cancelled` (missão
+  abandonada, com causa). Arquivar "para limpar" sem desfecho não é motivo.
+
+## Passos
+
+1. **Leia o squad real** (`squad.yaml`) e verifique o estado: a missão foi cumprida? Há trabalho em
+   voo (handoffs pendentes do squad em `.nexus/handoffs/`, frentes abertas)? Trabalho em voo é
+   listado ANTES da decisão — arquivar squad com frente aberta órfã trabalho em silêncio.
+2. **Apresente o resumo e PEÇA CONFIRMAÇÃO explícita** (ponto de elicitação — sagrado, por ser
+   ação destrutiva): id, missão, desfecho proposto (`completed`/`cancelled` + causa), trabalho em
+   voo encontrado. Sem o "sim" literal do usuário, HALT — não existe arquivamento em yolo.
+3. **Registre o desfecho no manifest:** `status: archived`, desfecho, data e motivo — o arquivo
+   conta a história completa para quem escavar depois.
+4. **Dispare o motor** (`nexus squad archive`): ele move `squads/{id}/` para
+   `squads/_archive/{id}/` — preservação, nunca `rm`. Eu não movo na mão nem deleto nada.
+5. **Prove:** confirme que `squads/{id}/` não está mais no roster ativo e que
+   `squads/_archive/{id}/` existe íntegro; reporte o resultado real.
+
+## Critério de pronto (DoD)
+
+- [ ] Estado do squad lido do disco; trabalho em voo enumerado antes da decisão
+- [ ] Confirmação explícita do usuário registrada (sem ela, nada aconteceu)
+- [ ] Desfecho (`completed`/`cancelled` + causa + data) gravado no manifest
+- [ ] Motor moveu para `squads/_archive/{id}/` — histórico preservado, zero deleção
+- [ ] Verificação pós-arquivamento reportada com resultado real
+
+## Falha / recuperação
+
+- **Usuário não confirma** → HALT limpo: nada foi movido, e o relatório diz isso.
+- **Trabalho em voo encontrado** → ofereça as opções numeradas: (1) concluir/handoff das frentes
+  antes de arquivar; (2) arquivar assim mesmo com as frentes NOMEADAS no desfecho; (3) cancelar.
+  Nunca arquive silenciando frente aberta.
+- **O motor falha ao mover** (permissão, conflito em `_archive/`) → reporte o erro exato e o estado
+  em que o squad ficou; não tente contornar movendo arquivos na mão.

package/tasks/audit-codebase.md

@@ -0,0 +1,53 @@
+---
+id: audit-codebase
+agent: ux-design-expert
+title: Auditar o codebase atrás de redundância de padrões de UI
+inputs: [path do codebase/diretório de UI]
+outputs: [inventário de padrões de UI, métricas de redundância, audit-report]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Auditar o codebase atrás de redundância de padrões de UI
+
+**Objetivo:** medir o caos antes de consertá-lo — inventariar componentes/padrões de UI existentes e
+quantificar a redundância com número real, para nunca consolidar no escuro.
+
+**Pré-condições:**
+- Foi informado um `path` válido para o codebase ou diretório de UI. Sem path, **pare** e elicite —
+  não audito o repositório inteiro por chute.
+- É um cenário brownfield (já existe UI). Em greenfield não há o que auditar — siga para
+  `setup-design-system`.
+
+## Passos
+
+1. **Varra o path** atrás de artefatos de UI: componentes, estilos, tokens implícitos (cores, fontes,
+   espaçamentos hardcoded), classes utilitárias, padrões repetidos. Use `Grep`/`Glob` para localizar.
+2. **Inventarie cada padrão encontrado** com sua localização (arquivo:linha) e suas propriedades
+   visuais — ex.: cada variação de botão com sua cor, raio, padding, fonte.
+3. **Quantifique a redundância:** quantos botões distintos? quantas cores diferentes para a mesma
+   intenção? quantos espaçamentos? Conte — "tem demais" não move ninguém; "47 botões" move.
+4. **Detecte hardcoded vs tokenizado:** marque todo valor visual cravado direto no código (hex,
+   px solto) — é dívida de design esperando para divergir.
+5. **Agrupe por tipo de átomo** (botões, inputs, cards, tipografia, cores) para preparar o terreno da
+   consolidação. NÃO consolide aqui — esta task só mede.
+6. **Gere o audit-report** em `docs/stories/{epic}/audit/audit-report.md` (ou caminho equivalente do
+   projeto) com inventário, contagens e localizações — números rastreáveis a arquivos reais.
+7. **Roteie o resultado** para `consolidate-patterns` (clustering) e, depois, `generate-shock-report`
+   (visual + ROI). A auditoria é o insumo factual desses dois.
+
+## Critério de pronto (DoD)
+
+- [ ] Path válido auditado; varredura cobriu componentes, estilos e valores hardcoded
+- [ ] Inventário com localização (arquivo:linha) de cada padrão
+- [ ] Métricas de redundância contadas (nº de variantes por tipo de átomo)
+- [ ] Valores hardcoded identificados e marcados
+- [ ] audit-report registrado, com números rastreáveis a arquivos reais
+
+## Falha / recuperação
+
+- **Path inválido ou vazio** → HALT e elicito o caminho correto; não audito o que não foi pedido.
+- **Codebase grande demais para uma passada** → fatio por diretório/tipo e audito em ondas, registrando
+  a cobertura de cada onda.
+- **Não encontrei padrões de UI** (não é frontend) → reporto que não há o que auditar e encerro; não
+  fabrico redundância inexistente.

package/tasks/build-component.md

@@ -0,0 +1,61 @@
+---
+id: build-component
+agent: ux-design-expert
+title: Construir um componente atômico de produção
+inputs: [nome do componente, design tokens, story/spec]
+outputs: [componente atômico + testes + a11y, 'docs/design-system/atoms/{componente}/']
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Construir um componente atômico de produção
+
+**Objetivo:** entregar um átomo de produção — componente tipado, testado, construído só sobre design
+tokens e com acessibilidade WCAG AA embutida — pronto para compor moléculas e ser integrado na app.
+
+**Pré-condições:**
+- O design system está inicializado (`setup-design-system`) e os tokens existem (`extract-tokens`).
+  Sem isso, **pare**: átomo sem tokens vira hardcode.
+- O componente rastreia a uma story/spec ou a um cluster consolidado. Sem rastro, elicito — não
+  invento componente que ninguém pediu.
+
+## Passos
+
+1. **Procuro o átomo antes de criar** (REUSE > ADAPT > CREATE). Se já existe um átomo que resolve,
+   reaproveito; se quase resolve, é caso de `extend-pattern` (variante), não de criar do zero. Só
+   crio quando nada serve — e registro o porquê.
+2. **Defino a API do componente** a partir da story/spec: props, variantes, estados (default, hover,
+   focus, disabled, loading, erro) — todos rastreando a uma necessidade real, não a um achismo.
+3. **Construo só com tokens.** Cor, espaçamento, tipografia, raio e sombra vêm de
+   `docs/design-system/tokens/` — zero hex/px solto. Hardcode aqui é bug de design esperando para
+   divergir.
+4. **Embuto acessibilidade WCAG AA desde o nascimento:** semântica correta (role/elemento),
+   navegação por teclado, foco visível, contraste validado, alt/aria onde aplicável. Não é "a11y
+   depois"; sem ela o componente não está pronto.
+5. **Escrevo os testes** que provam: cada variante/estado renderiza, o teclado navega, o foco é
+   visível, e os estados de erro/disabled se comportam. Não declaro pronto sem teste verde.
+6. **Rodo `accessibility-wcag-checklist`** no componente. Reprovou em AA → não entrego; corrijo
+   antes. Acessibilidade reprovada bloqueia a entrega.
+7. **Rodo lint + typecheck + os testes** do componente. Vermelho não vira entregue.
+8. **Documento o uso** (props, variantes, exemplos) para a pattern library e salvo tudo em
+   `docs/design-system/atoms/{componente}/`. Atualizo a File List da story.
+9. **Roteio.** Átomo pronto → @dev integra na app, @qa valida no fluxo. Pronto pra subir → @devops.
+   Eu construo o componente; quem publica é o Gage — nunca eu.
+
+## Critério de pronto (DoD)
+
+- [ ] Reuso checado antes de criar (REUSE > ADAPT > CREATE), com justificativa se criou do zero
+- [ ] Componente tipado, com todas as variantes/estados que a story pede
+- [ ] Zero valor hardcoded — tudo de design tokens
+- [ ] WCAG AA embutida (semântica, teclado, foco, contraste) e validada pelo checklist
+- [ ] Testes verdes; lint limpo; typecheck 0
+- [ ] Documentação de uso escrita; File List atualizada; nada subido por mim
+
+## Falha / recuperação
+
+- **Reprova WCAG AA** → HALT; não entrego. Corrijo a acessibilidade antes de qualquer coisa.
+- **Teste não passa após 3 tentativas no mesmo ponto** → HALT, registro o bloqueio, não empurro
+  gambiarra.
+- **A story não define a API o suficiente** → paro e devolvo ao @sm/@po; não invento props/variantes.
+- **Precisaria de valor fora dos tokens** → não hardcodo; volto à `extract-tokens` para o token
+  faltante (ou sinalizo a lacuna), e só então construo.

package/tasks/calculate-roi.md

@@ -0,0 +1,63 @@
+---
+id: calculate-roi
+agent: ux-design-expert
+title: Calcular ROI e economia de custo da consolidação
+inputs: [audit-report, consolidation-report]
+outputs: [número de ROI, economia estimada, breakdown rastreável]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Calcular ROI e economia de custo da consolidação
+
+**Objetivo:** transformar o caos medido (redundância de padrões de UI) em um número defensável —
+redução percentual, esforço economizado e custo evitado por ano — para justificar a consolidação com
+dado, não opinião.
+
+**Pré-condições:**
+- Existe um relatório de auditoria (`*audit`) com a contagem real de padrões redundantes. Se não
+  existe, **pare** — sem inventário, qualquer ROI é chute.
+- Existe (ou rodou) a consolidação (`*consolidate`) com o alvo de variantes finais. Sem o "depois",
+  não há delta para medir.
+
+## Passos
+
+1. **Puxo os números reais do `*audit`**: quantos padrões/variantes existem hoje (o "antes"). Não
+   estimo de cabeça — leio o inventário.
+2. **Puxo o alvo do `*consolidate`**: quantas variantes canônicas restam (o "depois"). O delta
+   antes→depois é a base de tudo.
+3. **Calculo a redução:**
+   - redução absoluta = (antes − depois)
+   - redução percentual = (antes − depois) / antes × 100
+   (ex.: 47 botões → 3 variantes = 44 eliminados, 93,6% de redução).
+4. **Estimo o esforço economizado.** Para cada padrão redundante eliminado, somo o custo recorrente que
+   ele gerava: manutenção, correção de bug duplicado, retrabalho de design, inconsistência. Uso premissas
+   explícitas de horas/padrão/ano — registro cada premissa para ser auditável.
+5. **Converto esforço em custo evitado/ano:** horas economizadas × custo-hora. Mantenho a premissa de
+   custo-hora explícita e separada (fácil de ajustar sem refazer a conta).
+6. **Calculo o ROI:** (custo evitado − custo da consolidação) / custo da consolidação. Incluo o custo de
+   fazer a consolidação (esforço de migração) para o número ser honesto, não inflado.
+7. **Monto o breakdown rastreável:** cada número aponta para a linha do `*audit`/`*consolidate` que o
+   originou, e cada premissa fica visível. Número sem rastro não convence ninguém.
+8. **Entrego o resultado** (anexo ao `*shock-report` quando houver) e roteio: a decisão de investir na
+   consolidação/migração com base no ROI é do @pm. Eu provo o valor; ele prioriza.
+
+## Critério de pronto (DoD)
+
+- [ ] "Antes" e "depois" puxados de `*audit` / `*consolidate` — nada estimado de cabeça
+- [ ] Redução absoluta e percentual calculadas e mostradas
+- [ ] Esforço economizado com premissas explícitas (horas/padrão/ano)
+- [ ] Custo evitado/ano com custo-hora explícito e separado
+- [ ] ROI inclui o custo da própria consolidação (número honesto)
+- [ ] Breakdown rastreável: cada número aponta para sua origem
+
+## Falha / recuperação
+
+- **Falta o inventário do `*audit`** → HALT; não calculo ROI sem o "antes" real. Rodo/peço a auditoria
+  primeiro.
+- **Premissa de custo-hora ou horas/padrão não tem base** → marco como premissa explícita e sinalizo a
+  incerteza; não escondo chute dentro do número.
+- **O número ficaria inflado** (ignorando o custo de migrar) → corrijo incluindo o custo da consolidação;
+  prefiro um ROI menor e defensável a um grande e furado.
+- **A decisão de priorizar a consolidação** → delego ao @pm; meu papel é provar o valor com número, não
+  decidir o backlog.