jarvis-ai-framework 3.0.0 → 3.2.0

package/agents/README.md

@@ -9,6 +9,7 @@ Este diretório contém **agentes especializados** organizados por domínio, usa
 ```
 agents/
 ├── engineering/                  # ⚙️ Agentes do domínio de Engenharia
+│   ├── eng.advisor.agent.md      # Advisor opcional das questões em aberto (eng.start)
 │   ├── eng.agent.md              # Agent principal de engenharia
 │   ├── eng.bug-hunter.md         # Caça e análise de bugs
 │   ├── eng.dev-code-reviewer.md  # Code reviewer
@@ -44,6 +45,7 @@ Agentes específicos para fluxos e regras do domínio de Engenharia.
 - `eng.rpa.agent.md` - `@eng.rpa` - Automação e scraping RPA (ARACHNE)
 - `eng.frontend.agent.md` - `@eng.frontend` - Especialista frontend (neutro de stack): UI, estado, performance, a11y
 - `eng.ux-designer.agent.md` - `@eng.ux-designer` - Especialista UX/UI: heurísticas Nielsen, jornada, microcopy
+- `eng.advisor.agent.md` - `@eng.advisor.agent` - Advisor opcional: orienta as questões em aberto do `eng.start` (modelo escolhido pelo usuário)
 
 
 ### Data Agents (1)

package/agents/engineering/eng.advisor.agent.md

@@ -0,0 +1,56 @@
+---
+name: eng.advisor.agent
+description: >
+  Advisor opcional do eng.start: recebe as questões em aberto do architecture.md, uma por vez,
+  analisa o contexto da tarefa (card, documentos de especificação, sessão e repositório, só leitura)
+  e devolve a sugestão mais adequada, que é adotada como decisão. Não escreve, não executa.
+  Trigger: o usuário escolheu usar o Advisor no início do eng.start e o architecture.md tem questões em aberto.
+tools: Read, Glob, Grep, Bash
+---
+
+# Advisor (eng.advisor.agent)
+
+## Papel
+
+Você esclarece as dúvidas do agente principal. Recebe uma questão em aberto, entende, analisa o repositório **só se precisar para ter certeza (sem chutar)** e devolve a sugestão mais adequada, que é adotada como decisão final daquela questão. Você **não** escreve documentos, **não** executa mudanças, **não** edita arquivos, **não** troca de branch e **não** faz commit. No GitHub, **só consulta** (`gh issue view`, `gh issue list`, `gh pr view`): nunca cria, edita, comenta nem fecha nada. A análise do card, a documentação, a execução e os registros são do agente principal.
+
+> O modelo é escolhido pelo usuário no `eng.start` e passado na invocação; por isso este arquivo não declara `model:`.
+
+## Fluxo
+
+Os textos dos dois passos estão em `$IDE/templates/engineering/advisor-template.md`; o agente principal os preenche e envia.
+
+1. **Carga inicial** (uma vez por tarefa, na primeira questão em aberto): leia as fontes de contexto abaixo e responda **só** "Contexto lido" + os caminhos que leu + uma frase de até 20 palavras sobre o objetivo da tarefa. Se o contexto for **insuficiente para orientar** (por exemplo, o card cita um PRD que você não achou), responda "Preciso de ajuda para localizar o contexto", dizendo onde procurou e o que precisa; o agente principal pergunta ao usuário e reenvia. Se o card bastar, siga sem perguntar.
+2. **Questão em aberto** (uma mensagem por questão, nesta mesma instância): responda no formato de "Saída".
+
+## Fontes de contexto
+
+Use só o que existir, nesta ordem:
+
+1. **O card** (`TASK_MANAGER_KEY`) e o que ele referencia; com `TASK_MANAGER=github`, leia a issue e as issues e PRs citados com `gh` (só leitura).
+2. **Os documentos de especificação** no formato de `$IDE/templates/product/`: a partir da história, tarefa, bug ou épico em `$PROD_DOCS` cujo `task_link`, id ou nome corresponda ao card, siga `related_prd`, `related_frd`, `related_epic` e `related_discovery`.
+3. **As pastas de sessão** `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/` e `$SESSIONS_DIR/prod/{TASK_MANAGER_KEY}/`: `architecture.md`, `context.md` e qualquer relatório ou rascunho.
+4. **O repositório**, em modo somente leitura, para confirmar fatos.
+
+## Saída
+
+Até ~250 palavras, nesta ordem:
+
+1. **SUGESTÃO DO ADVISOR:** opção 1, 2 ou 3, ou a **4 — Outra** detalhada (como funciona, vantagens, desvantagens, impacto).
+2. **DIVERGÊNCIA:** se discordar da sugestão do agente principal, o motivo técnico; senão "sem divergência".
+3. **BASE:** em que documento, card ou sessão você se apoia.
+4. **ANÁLISE NO REPOSITÓRIO:** arquivos e linhas que leu, ou "não foi necessário".
+5. **RELAÇÃO COM OUTRAS TAREFAS:** algo que outra issue cubra e mude a sugestão.
+6. **CERTEZA:** alta, média ou baixa, separando o que está **escrito** nos documentos, o que foi **confirmado** no código e o que é **inferência**. Se os documentos não cobrirem a questão, diga isso.
+
+Se uma opção for destrutiva ou fugir do que o card pede, aponte o risco.
+
+## Skills Disponíveis
+
+Nenhuma — agente autocontido, não depende de skill
+
+## Workflows e Agentes Relacionados
+
+- **eng.start**: abre este agente quando o usuário escolhe usar o Advisor e há questões em aberto
+- **eng.plan**: consulta por exceção, se surgir questão nova em aberto
+- **eng.work**: consulta por exceção, se surgir questão nova em aberto

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jarvis-ai-framework",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Jarvis framework",
   "type": "module",
   "bin": {

package/rules/engineering/eng.integrations-rules.md

@@ -34,7 +34,9 @@ Com board definido, se o key não veio nos argumentos, perguntar o id do card na
 
 ## Comentário no card
 
-Só se `TASK_MANAGER` estiver preenchido com um vendor. Freelance → pular.
+Só se `TASK_MANAGER` estiver preenchido com um vendor. Freelance → pular. Falha no comentário não bloqueia o workflow.
+
+Comentar **somente** em eventos relevantes: (a) **desvio do plano** (mudança de direção, fase bloqueada), (b) **auditoria do Advisor** (as questões do `architecture.md` com as opções junto da escolha), (c) **bloqueio** com valor de rastreabilidade (ex.: pré-PR reprovado), (d) **link do MR**, uma única vez. **Nunca** comentar início ou fim de etapa ("Iniciando…", "concluído…"): o acompanhamento fica no fluxo e no PR.
 
 ```
 /eng-global-task-comment {TASK_MANAGER_KEY} {mensagem}

package/rules-on-demand/engineering/eng.pre-pr-rules.md

@@ -94,6 +94,6 @@ O workflow **deve sempre** terminar com:
    - 🟡 Yellow: pode abrir PR com ressalvas documentadas
    - 🔴 Red: bloqueado — listar o que impede o PR
 
-2. **Comentário no card** com o status final (via `/eng-global-task-comment`) — pular se freelance
+2. **Comentário no card só se a validação reprovar** (🔴 RED, bloqueio), com o motivo (via `/eng-global-task-comment`) — pular se freelance; GREEN e YELLOW não comentam
 
 3. **Aguardar permissão explícita** do usuário para prosseguir para `/eng.pr`

package/rules-on-demand/engineering/eng.start-rules.md

@@ -44,6 +44,8 @@ O workflow **só é considerado completo** após:
 2. O usuário revisar o documento
 3. O usuário **aprovar explicitamente** para prosseguir
 
+**Exceção (Advisor):** se o usuário escolheu usar o Advisor no início do `eng.start`, as questões em aberto são decididas pela sugestão dele e o gate segue a autonomia do `context.md`: com `autonomia: alta` o `start` apresenta o resumo e segue para o `eng.plan` sem aguardar; com `média` ou `baixa`, a aprovação explícita continua obrigatória.
+
 ---
 
 ## Comportamento Esperado

package/skills/eng-global-task-comment/SKILL.md

@@ -2,7 +2,7 @@
 name: eng-global-task-comment
 description: >
   Adiciona um comentário no card do TASK_MANAGER (Jira, Linear, GitHub Issues ou Asana).
-  Trigger: registrar progresso, início ou fim de etapa em um card.
+  Trigger: registrar no card um evento relevante: desvio do plano, auditoria do Advisor, bloqueio ou o link do MR (nunca início ou fim de etapa).
 argument-hint: "{TASK_MANAGER_KEY} {mensagem}"
 disable-model-invocation: false
 allowed-tools: Read Bash MCP

package/skills/jarvis-init/SKILL.md

@@ -588,6 +588,7 @@ Nunca grave TOKEN_VERSION_CONTROL (chave removida do template).
 | `CENTRAL_DOCS_REPO` / `_REF` / `_TARGET_BRANCH` / `_REVIEWERS` / `_CACHE_TTL` | *(opcional)* | Docs centrais |
 | `SESSIONS_DIR` | `.jarvis/sessions` | Não perguntar — gravar fixo |
 | `RTK_ENABLED` | `false` (ou true se detectar `rtk`) | Token Killer |
+| `ADVISOR_MODELS` | `"Sonnet 5.5,Opus 5.5,Opus 5,Fable 5.1"` | Advisor do `eng.start` — não perguntar, gravar o padrão |
 
 #### 4.1 Detecção do RTK (Token Killer)
 

package/templates/AGENTS.md

@@ -16,6 +16,7 @@ A pasta `templates/` contem **modelos de documentos** usados pelo framework para
 templates/
 ├── engineering/                    # Templates tecnicos
 │   ├── architecture-template.md    # Template de arquitetura
+│   ├── advisor-template.md         # Prompts e auditoria do Advisor
 │   ├── ARD-template.md             # Architecture Review Document
 │   ├── RFC-template.md             # Request For Comments
 │   ├── RFC-Playbook@1.0.0.md       # Playbook para RFCs
@@ -105,6 +106,7 @@ Use chaves `{...}` para indicar campos a serem preenchidos:
 | Template | Uso | Comando |
 |----------|-----|---------|
 | `architecture-template.md` | Design arquitetural | `/eng.start` |
+| `advisor-template.md` | Prompts do Advisor e modelo de auditoria | `/eng.start` |
 | `ARD-template.md` | Revisao de arquitetura | `/eng.create-ard` |
 | `RFC-template.md` | Proposta de mudanca | `/eng.create-rfc` |
 | `tech-spec-template.md` | Especificacao tecnica | `/eng.build-tech-spec` |

package/templates/ENV-template.md

@@ -144,6 +144,16 @@ SMTP=[google, ses, sendgrid]
 RTK_ENABLED=false
 
 
+# --- Advisor (opcional) ------------------------------------------------------
+# Modelos oferecidos quando o usuário escolhe usar o Advisor no início do eng.start,
+# separados por vírgula. Até 4 viram opções da pergunta; o resto fica em "Outro".
+# Vazio ou ausente = o Advisor usa "Sonnet 5.5" (fallback).
+# Tradução para a IDE pela família (primeira palavra, em minúsculas: Sonnet → sonnet,
+# Opus → opus, Fable → fable). No Claude Code só a família é respeitada: "Opus 5.5"
+# e "Opus 5" abrem o mesmo modelo; remova um deles se quiser só opções distintas.
+ADVISOR_MODELS="Sonnet 5.5,Opus 5.5,Opus 5,Fable 5.1"
+
+
 # --- Data Engineering (só se HUB=DATA) ---------------------------------------
 # Obrigatório quando HUB=DATA. Omitir o bloco inteiro se o HUB for outro.
 DATA_ORCHESTRATOR=[airflow, prefect, dagster, glue-scheduler]

package/templates/engineering/advisor-template.md

@@ -0,0 +1,65 @@
+# Advisor — prompts e auditoria
+
+> Usado pelo `eng.start` (e, por exceção, pelo `eng.plan` e pelo `eng.work`) com o agente `eng.advisor.agent`. Os campos `{...}` são preenchidos pelo agente principal.
+
+## Prompt 1 — Carga inicial (uma vez por tarefa, na primeira questão em aberto)
+
+```
+Você é o Advisor desta tarefa ({TASK_MANAGER_KEY}). Você esclarece as questões em aberto que eu enviar, uma por vez, e devolve a sugestão mais adequada; ela é adotada como decisão final. Eu (agente principal) faço a análise do card, a documentação, a execução e os registros.
+
+Agora, somente leitura (não edite, não troque de branch, não faça commit; no GitHub, só consulta): leia as fontes de contexto do seu arquivo de agente — card, documentos de especificação ($PROD_DOCS, seguindo task_link e related_*), pastas de sessão ({SESSAO_ENG} e {SESSAO_PROD}) e, se preciso, o repositório {REPO}.
+
+Etapas da tarefa:
+| Etapa | O que acontece | Onde o Advisor entra |
+| Alerta no início do eng.start | O usuário escolhe usar o Advisor e o modelo | Ainda não existe |
+| eng.start | Escrevo o architecture.md; o que diverge do código ou é ambíguo vira "Questões em Aberto" | Aqui: você orienta cada questão |
+| Orientação acatada | Atualizo o architecture.md e registro | Não |
+| Registro da auditoria | Posto um comentário na issue com as questões e as suas sugestões (sem TASK_MANAGER, só no architecture.md) | Não |
+| eng.plan / eng.work | Plano e implementação | Só por exceção: questão nova em aberto |
+| Commit e PR | Um commit; o usuário valida em "Files changed" | Não |
+| Merge e fechamento | O usuário faz o merge | Não |
+
+Responda SOMENTE com "Contexto lido" + os caminhos que leu + uma frase de até 20 palavras sobre o objetivo da tarefa. Se o contexto for insuficiente para orientar, responda "Preciso de ajuda para localizar o contexto", dizendo onde procurou e o que precisa.
+```
+
+## Prompt 2 — Questão em aberto (uma mensagem por questão)
+
+```
+Questão {QN} de {TOTAL} ({TASK_MANAGER_KEY}). Texto completo na seção 8 do architecture.md ({CAMINHO}).
+
+Contexto: {por que a dúvida existe e o impacto na implementação}
+Arquivos/componentes envolvidos: {arquivo — relação}
+Dúvida: {o que precisa ser decidido}
+Opções:
+1. {opção} — como funciona, vantagens, desvantagens, impacto
+2. {opção} — ...
+3. {opção} — ...
+4. Outra (sua, se houver)
+Sugestão do agente principal: {N}, porque {motivo}
+
+Analise o repositório só se precisar para ter certeza (sem chutar). Responda (até ~250 palavras):
+1. SUGESTÃO DO ADVISOR (opção 1-3 ou a 4 detalhada) · 2. DIVERGÊNCIA · 3. BASE · 4. ANÁLISE NO REPOSITÓRIO · 5. RELAÇÃO COM OUTRAS TAREFAS · 6. CERTEZA (escrito / confirmado no código / inferência). Não altere arquivos; aponte o risco se uma opção for destrutiva ou fugir do card.
+```
+
+## Modelo do comentário de auditoria (postado pelo agente principal)
+
+```
+## Auditoria — questões do architecture.md
+
+Questões levantadas no `architecture.md` desta issue e a sugestão do Advisor ({modelo}). **A sugestão do Advisor prevalece e é a decisão adotada.** Análise, documentação, execução e este registro são do agente principal.
+
+### {QN} — {título}
+- **Contexto:** {...}
+- **Arquivos envolvidos:** {...}
+- **Opções:** 1 — {...} · 2 — {...} · 3 — {...} · 4 — Outra
+- **Sugestão do agente principal:** {N}
+- **Sugestão do Advisor (decisão adotada):** **{N}**
+- **Divergência:** {motivo técnico, ou "sem divergência"}
+- **Base:** {...}
+- **Análise no repositório:** {arquivos e linhas, ou "não foi necessário"}
+- **Certeza:** {alta|média|baixa} — escrito: {...}; confirmado no código: {...}; inferência: {...}
+- **Impacto da decisão:** {...}
+- **Levantada em:** {eng.start | eng.plan | eng.work} (fora do eng.start, é lacuna a citar no PR)
+
+Link do PR: {#PR} (preenchido quando existir; se a decisão for revista na execução, atualizar este mesmo comentário)
+```

package/templates/engineering/architecture-template.md

@@ -5,7 +5,8 @@
 
 > **Criado em:** {DATA}  
 > **Issue:** {JIRA_ISSUE_KEY}  
-> **Status:** 🔄 Em Revisão | ✅ Aprovado | ❌ Rejeitado
+> **Status:** 🔄 Em Revisão | ✅ Aprovado | ❌ Rejeitado  
+> **Advisor:** {modelo escolhido no início do eng.start} | não utilizado
 
 ---
 
@@ -245,9 +246,56 @@ graph TD
 
 ## 8. Questões em Aberto
 
-| ID  | Questão                        | Responsável | Deadline | Status   |
-| --- | ------------------------------ | ----------- | -------- | -------- |
-| Q1  | {questão ainda não respondida} | {quem}      | {data}   | 🔄 Aberta |
+> Tudo que for **diferente do código ou ambíguo no card** vira uma questão aqui, detalhada a ponto de outro agente entendê-la sem reconstruir a análise. No mínimo 3 opções, mais a **4 — Outra**.
+> **Com Advisor** (cabeçalho), a sugestão do Advisor prevalece e é a decisão adotada; o agente principal não a substitui nem contesta. **Sem Advisor**, "Sugestão do Sub-Agent (Advisor)" e "Divergência" ficam "N/A (Advisor não utilizado)", a regra em destaque é omitida e a decisão é a do usuário ao revisar o documento.
+> Questão levantada depois do `eng.start` (consulta por exceção) entra aqui, numerada em sequência, marcada "levantada no `eng.plan`" ou "no `eng.work`". Sem questão em aberto, escreva "Nenhuma" e o motivo em uma frase.
+
+| ID | Questão                      | Responsável                 | Deadline | Status                     |
+| -- | ---------------------------- | --------------------------- | -------- | -------------------------- |
+| Q1 | {resumo objetivo da questão} | {Advisor \| nome do usuário} | {— \| data} | {✅ Decidida \| 🔄 Aberta} |
+
+### Q1 — {Título da questão}
+
+**Contexto:**
+{Explicação detalhada do problema e por que a decisão é necessária.}
+
+**Arquivos/componentes envolvidos:**
+* `{arquivo/caminho}` — {relação com a questão}
+
+**Dúvida:**
+{Descrição clara e inequívoca do que precisa ser decidido.}
+
+**Opções:**
+
+**1. {Opção 1}**
+* Como funciona: {descrição}
+* Vantagens: {vantagens}
+* Desvantagens: {desvantagens}
+* Impacto: {impacto}
+
+**2. {Opção 2}** (mesmo formato)
+
+**3. {Opção 3}** (mesmo formato)
+
+**4. Outra**
+* Alternativa adicional identificada pelo Sub-Agent/Advisor, detalhada caso ele entenda que nenhuma das opções anteriores é a melhor abordagem.
+
+**Sugestão do Agente Principal (Architect):**
+{recomendação do agente principal + justificativa técnica}
+
+**Sugestão do Sub-Agent (Advisor):**
+{recomendação independente do Advisor + justificativa técnica}
+
+**Decisão adotada:**
+**{recomendação do Sub-Agent/Advisor}**
+
+> **Regra:** a recomendação do Advisor sempre prevalece e deve ser adotada na implementação, independentemente de ser igual ou diferente da recomendação do Agente Principal.
+
+**Divergência:**
+{se houver diferença entre as recomendações, explicar objetivamente por que o Advisor escolheu uma abordagem diferente.}
+
+**Impacto da decisão:**
+{consequências da decisão adotada para a arquitetura e implementação.}
 
 ---
 

package/workflows/engineering/eng.plan.md

@@ -41,25 +41,11 @@ Antes de executar este workflow:
 | Passo | Skill | Condição |
 |-------|-------|----------|
 | Cabeçalho (agente) | `eng.agent` (agente) | Sempre — identidade do workflow |
-| Fase 0.5: Comentário no card — Início | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver preenchido (freelance pula) |
 | Fase 0 › 0.1 Herdar Contexto da Sessão | `/jarvis-context-detect` | Se `ENABLE_CDD=true` e o `context.md` não existir |
 | Fase 2: Pesquisa no Codebase | `repoprompt` (MCP: `search`, `read_selected_files`) | Para buscar e ler arquivos relevantes do codebase |
 | Fase 2: Pesquisa no Codebase (se necessário) | `context7` (MCP) | Se for preciso consultar a documentação de bibliotecas |
-| Comentário no card — Conclusão | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver preenchido, após validar o plano com o usuário (freelance pula) |
-
----
-
-## Fase 0.5: Comentário no card — Início
-
-Pular se `TASK_MANAGER` estiver vazio (freelance).
-
-Após confirmar que o `architecture.md` existe, registrar início do planejamento:
-
-```
-/eng-global-task-comment {TASK_MANAGER_KEY} 📋 [Jarvis] Iniciando criação do plano de execução
-```
-
-> Usa o skill `/eng-global-task-comment`. Não bloquear se falhar.
+| Fase 3: Criação do Plano (exceção) | `eng.advisor.agent` (agente) | Só por exceção: questão nova em aberto, com o Advisor habilitado no `eng.start` (cabeçalho do `architecture.md`) |
+| Fase 3: Criação do Plano (exceção) | `/eng-global-task-comment` | Só por exceção: comentário de auditoria da questão nova consultada ao Advisor (freelance pula) |
 
 ---
 
@@ -174,6 +160,8 @@ CONTEXT_PROFILE:
 
 4. **Usar** o template em `$IDE/templates/engineering/plan-template.md`
 
+**Questão nova em aberto (exceção).** O ideal é que todas as questões tenham sido levantadas no `eng.start`. Se surgir uma nova e o cabeçalho do `architecture.md` indicar um Advisor, consulte `eng.advisor.agent` com o Prompt 2 de `$IDE/templates/engineering/advisor-template.md` (refaça o Prompt 1 se o subagente não existir mais), acrescente a questão à seção 8 marcada "levantada no `eng.plan`", adote a sugestão do Advisor e poste o comentário de auditoria com `/eng-global-task-comment` (é desvio do plano; cite-o no PR como lacuna do `eng.start`). Sem Advisor, pergunte ao usuário.
+
 ### Fase 4: Validação
 
 1. **Apresentar** o plano ao humano
@@ -200,16 +188,6 @@ Com:
 
 ---
 
-## Comentário no card — Conclusão
-
-Pular se `TASK_MANAGER` estiver vazio (freelance).
-
-Após validação do plano com o usuário, registrar conclusão:
-
-```
-/eng-global-task-comment {TASK_MANAGER_KEY} ✅ [Jarvis] Plano de execução criado e validado - {N} fases definidas. Pronto para implementação.
-```
-
 ## Próximo Passo
 
 Após a validação do plano com o humano, informar:

package/workflows/engineering/eng.pr.md

@@ -43,9 +43,8 @@ Este comando cria a **branch, commita as alterações e abre um Merge Request**.
 | Fase 1 › 1.4 Executar Testes Automatizados (Opcional) | `/eng-qa` + `QA_SPECIALIZATIONS` | Passo opcional, recomendado em mudanças significativas |
 | Skills recomendados | `/eng-global-docs-write` | Se houver necessidade de atualizar documentação junto do PR |
 | Agentes recomendados (opcional) | `eng.qa.test-planner` (agente) | Se houver dúvidas sobre cobertura de testes ou mudanças significativas |
-| Fase 0.5: Comentário no card — Início | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver preenchido (freelance pula) |
 | Fase 4 › 4.2 Criar MR/PR via adapter | `jarvis vcs create-merge` (CLI do Jarvis) | Sempre — abre o MR/PR conforme `VERSION_CONTROL` ou o host do `origin` |
-| Fase 5: Comentário no card — Conclusão | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver preenchido, depois de o MR ser criado (freelance pula) |
+| Fase 6 › 6.2 Link do MR | `/eng-global-task-comment` | Depois de o MR ser criado: um único comentário no card com o link do MR, seguindo o Passo 6 do skill `eng-global-pr` (freelance pula) |
 
 ---
 
@@ -67,20 +66,6 @@ Ler `TASK_MANAGER` do `$IDE/ENV.md`. Seguir `$IDE/rules/engineering/eng.integrat
 
 ---
 
-## Fase 0.5: Comentário no card — Início
-
-Pular se `TASK_MANAGER` estiver vazio (freelance).
-
-Registrar início da criação do MR:
-
-```
-/eng-global-task-comment {TASK_MANAGER_KEY} 🔀 [Jarvis] Iniciando criação do Merge Request para {TARGET_BRANCH}
-```
-
-> Usa o skill `/eng-global-task-comment`. Não bloquear se falhar.
-
----
-
 ## Fase 1: Validação Pré-PR
 
 ### 1.1 Executar Testes Unitários
@@ -248,18 +233,6 @@ Se o CLI `jarvis` não estiver instalado no repo alvo, usar `node {caminho-do-cl
 
 ---
 
-## Fase 5: Comentário no card — Conclusão
-
-Pular se `TASK_MANAGER` estiver vazio (freelance).
-
-Após MR criado com sucesso, registrar:
-
-```
-/eng-global-task-comment {TASK_MANAGER_KEY} ✅ [Jarvis] MR criado: {TITULO_DO_MR} → {TARGET_BRANCH} | Link: {LINK_DO_MR}
-```
-
----
-
 ## Fase 6: Atualizar Board
 
 Pular se `TASK_MANAGER` estiver vazio (freelance).
@@ -268,14 +241,9 @@ Pular se `TASK_MANAGER` estiver vazio (freelance).
 
 Mova o card para a etapa equivalente a "em revisão" no seu board. Quem assumiu o card o move; não é preciso esperar o TECH LEAD ou o PM.
 
-### 6.2 Adicionar Comentário
-
-Adicione um comentário no card com o link do MR:
+### 6.2 Link do MR no card
 
-```
-MR aberto: {LINK_DO_MR}
-Branch: {NOME_DA_BRANCH}
-```
+Siga o Passo 6 do skill `eng-global-pr`: um único comentário no card, com o link e a branch. É o único comentário do `eng.pr` no card.
 
 ---
 

package/workflows/engineering/eng.pre-pr.md

@@ -40,7 +40,6 @@ Estamos nos aproximando de finalizar o trabalho nesta branch e nos preparar para
 | Skills recomendados | `/jarvis-docs-index` | Se for necessário atualizar o índice de documentação |
 | Skills recomendados | `/eng-platform` + `PLATFORM_SPECIALIZATIONS` | Se a feature tiver requisitos não-funcionais de latência, throughput ou escalabilidade |
 | Skills recomendados | `/eng-backend` e `/eng-frontend` (via `eng.specializations-rules.md`) | Para validar código de backend (endpoints, autenticação, workers) ou de frontend (componentes, performance de UI, WCAG 2.1 AA); a regra também carrega as especializações registradas no ENV.md |
-| Fase 0.5: Comentário no card — Início | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver preenchido (freelance pula) |
 | Gate 0: Verificar Documentação Central | `/jarvis-docs-central` (via `jarvis docs publish --tipo ard`) | Se `CENTRAL_DOCS_REPO` estiver configurado, houver mudança arquitetural, o ARD estiver desatualizado ou novo e o usuário aceitar publicar |
 | Gates › item 1 | `prod.pm-checker` (agente) | Sempre — verificar alinhamento da branch com os docs de produto e engenharia |
 | Gates › item 2 | `eng.dev-code-reviewer` (agente) | Sempre — revisar o código antes de lançar |
@@ -52,21 +51,7 @@ Estamos nos aproximando de finalizar o trabalho nesta branch e nos preparar para
 | Gates › item 8 | `eng.ux-designer.agent` (agente) | Se a branch introduzir nova feature de UI ou alterar fluxo de usuário |
 | Gates › item 9 | `eng.docs-writer` (agente) | Sempre — atualizar a documentação do projeto |
 | Gates › item 10 | Nenhuma — checklist inline | Se a branch tocar em auth, sessions, inputs de usuário, CORS, CSP, permissões ou adicionar endpoints públicos |
-| Comentário no card — Conclusão | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver preenchido, com o status final (freelance pula) |
-
-## Fase 0.5: Comentário no card — Início
-
-Pular se `TASK_MANAGER` estiver vazio (freelance).
-
-Ao iniciar o pre-PR, registrar:
-
-```
-/eng-global-task-comment {TASK_MANAGER_KEY} 🔍 [Jarvis] Iniciando validação pre-PR - bateria de testes e revisão de código
-```
-
-> Usa o skill `/eng-global-task-comment`. Não bloquear se falhar.
-
----
+| Saída final › 2) Bloqueadores e pendências | `/eng-global-task-comment` | Só se a validação reprovar (status RED): um comentário com o motivo (freelance pula) |
 
 ## Regras de Execução
 
@@ -150,6 +135,8 @@ Você também precisará lidar com todo o feedback que esses agentes fornecerem
 
 ### 2) Bloqueadores e pendências
 
+Se o status for **RED** (bloqueado), comente o bloqueio e o motivo no card com `/eng-global-task-comment` (freelance pula). GREEN e YELLOW não geram comentário.
+
 - Bloqueadores:
 - Pendências aceitas (com justificativa):
 - Follow-ups (links/IDs):
@@ -162,20 +149,4 @@ Você também precisará lidar com todo o feedback que esses agentes fornecerem
 - Docs atualizadas:
 - Riscos / trade-offs:
 
-## Comentário no card — Conclusão
-
-Pular se `TASK_MANAGER` estiver vazio (freelance).
-
-Após apresentar o resultado final, registrar:
-
-- Se **Green**: `✅ [Jarvis] Pre-PR concluído com status GREEN - pronto para abrir MR`
-- Se **Yellow**: `⚠️ [Jarvis] Pre-PR concluído com status YELLOW - pode abrir MR com ressalvas`
-- Se **Red**: `🚫 [Jarvis] Pre-PR concluído com status RED - bloqueadores encontrados, não abrir MR`
-
-```
-/eng-global-task-comment {TASK_MANAGER_KEY} {mensagem_status}
-```
-
----
-
 Uma vez terminado, me avise e peça minha permissão para abrir o Pull Request.

package/workflows/engineering/eng.start.md

@@ -26,7 +26,7 @@ Este comando inicia o **planejamento** de uma nova feature.
 |-------|-------|----------|
 | Cabeçalho (agente) | `eng.agent` (agente) | Sempre — identidade do workflow |
 | Fase 0.1: Análise de Contexto (CDD) | `/jarvis-context-detect` | Se `ENABLE_CDD=true` no ENV.md (execução obrigatória antes da Fase 1); `ENABLE_CDD=false` pula |
-| Fase 0.5: Comentário no card — Início | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver preenchido (freelance pula) |
+| Fase 0.5: Advisor (opcional) | `eng.advisor.agent` (agente) | Se o usuário escolher usar o Advisor no alerta e o `architecture.md` tiver questões em aberto (aberto só na primeira questão) |
 | Fase 2.2: Buscar Documentação Central | `/jarvis-docs-central` | Se `CENTRAL_DOCS_REPO` estiver configurado no ENV.md (buscar PRD, ARD e RFCs relacionados) |
 | Fase 3.4: Estratégia de Testes | `eng.qa.test-architect` (agente) | Se a feature tiver requisitos de performance ou segurança (APIs públicas, dados sensíveis, alta carga ou requisitos não-funcionais explícitos) |
 | Fase 3.4: Estratégia de Testes | `/eng-platform` | Se a feature tiver requisitos de performance (latência, throughput, escalabilidade) |
@@ -36,7 +36,7 @@ Este comando inicia o **planejamento** de uma nova feature.
 | Fase 3.4: Estratégia de Testes | `/eng-data` (via `eng.specializations-rules.md`) | Se a feature envolver engenharia de dados (pipelines ETL/ELT, Glue, Airflow, contratos de dados, camadas bronze/silver/gold); a regra também carrega as especializações de `DATA_SPECIALIZATIONS` |
 | Fase 3.4: Estratégia de Testes | `/eng-automation` (via `eng.specializations-rules.md`) | Se a feature envolver RPA ou extração de dados/scraping; a regra também carrega as especializações de `AUTOMATION_SPECIALIZATIONS` |
 | Fase 3.4: Estratégia de Testes | `/eng-platform` (via `eng.specializations-rules.md`) | Se a feature envolver infraestrutura (IaC, contêineres, CI/CD, observabilidade, SRE, custo); a regra também carrega as especializações de `PLATFORM_SPECIALIZATIONS` |
-| Fase 5.4: Comentário no card — Conclusão | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver preenchido, após o usuário aprovar o `architecture.md` (freelance pula) |
+| Fase 4.3: Questões em Aberto | `/eng-global-task-comment` | Se o Advisor foi usado e houve questões em aberto: **um** comentário de auditoria (freelance pula; o registro fica só no `architecture.md`) |
 
 ---
 
@@ -123,17 +123,13 @@ Se o usuário solicitar ajustes, re-execute com `--override`.
 
 ---
 
-## Fase 0.5: Comentário no card — Início
+## Fase 0.5: Advisor (opcional)
 
-Pular se `TASK_MANAGER` estiver vazio (freelance).
-
-Após obter o `TASK_MANAGER_KEY`, registrar o início do planejamento:
+Logo depois de obter o `TASK_MANAGER_KEY`, pergunte com `AskUserQuestion` (sem a ferramenta, use a tabela de `prod-rules.md`): **"Usar o Advisor nas questões em aberto desta tarefa?"** (**Não**, padrão / **Sim**). Com **Não**, siga como sempre e não mencione mais o Advisor.
 
-```
-/eng-global-task-comment {TASK_MANAGER_KEY} 🚀 [Jarvis] Iniciando planejamento - architecture.md sendo criado
-```
+Com **Sim**, pergunte **"Qual modelo para o Advisor?"** com os itens de `ADVISOR_MODELS` do `ENV.md` (até 4 opções; o resto em "Outro"). Lista vazia ou ausente: use `Sonnet 5.5` sem perguntar; lista de um item: use-o sem perguntar. Traduza o nome pela família (primeira palavra em minúsculas: `sonnet`, `opus`, `fable`, `haiku`); se o modelo não for aceito pela IDE, use `sonnet` e avise em uma linha. Se a IDE não permitir escolher o modelo do subagente, avise e não faça a segunda pergunta.
 
-> Usa o skill `/eng-global-task-comment` (MCP Atlassian → fallback curl). Não bloquear se falhar.
+Registre a escolha no cabeçalho do `architecture.md` (`Advisor:`). O agente `eng.advisor.agent` só é aberto na primeira questão em aberto (Fase 4.3).
 
 ---
 
@@ -382,6 +378,18 @@ Preencha **TODAS** as seções com as informações coletadas nas fases anterior
 - Use nomes de classes/funções existentes
 - Referencie código encontrado na investigação
 
+### 4.3 Questões em Aberto
+
+Levante na seção 8 **tudo** que for diferente do código ou ambíguo no card, no formato do template (é aqui que as questões devem aparecer; levantá-las depois é exceção).
+
+**Com Advisor** (Fase 0.5), use os textos de `$IDE/templates/engineering/advisor-template.md`:
+1. Na primeira questão, abra `eng.advisor.agent` em segundo plano com o modelo escolhido e envie o **Prompt 1** (carga inicial). Se ele responder que precisa de ajuda para localizar o contexto, pergunte ao usuário com `AskUserQuestion` (opção "Não há documento: siga só com o card e o código") e reenvie.
+2. Envie cada questão com o **Prompt 2**, uma por mensagem, para a mesma instância.
+3. Preencha "Sugestão do Sub-Agent (Advisor)", **"Decisão adotada" (a sugestão do Advisor, que prevalece; não a substitua nem a conteste)**, "Divergência" e "Impacto da decisão". Confira no código os fatos em que a sugestão se apoia antes de registrar.
+4. Poste **um** comentário de auditoria na issue com `/eng-global-task-comment`, no modelo do template (freelance pula).
+
+**Sem Advisor:** apresente as questões ao usuário, como sempre.
+
 ---
 
 ## Fase 5: Revisão e Aprovação
@@ -403,23 +411,15 @@ Se o usuário tiver feedback:
 - Apresente novamente
 - Continue até aprovação explícita
 
+**Com Advisor**, o gate segue a autonomia do `context.md` (CDD): `alta` → apresente o resumo e siga para o `eng.plan` sem aguardar; `média` ou `baixa` → aguarde a aprovação explícita. Sem `context.md`, use a tabela "Autonomia por POSITION" de `eng-rules.md`. Sem Advisor, nada muda.
+
 ### 5.3 Atualizar Board
 
 Pular se `TASK_MANAGER` estiver vazio (freelance).
 
 Se estiver preenchido, mova o card para a etapa equivalente a "em andamento" no seu board. Quem assumiu o card conduz a entrega; ninguém precisa liberar a transição.
 
-### 5.4 Comentário no card — Conclusão
-
-Pular se `TASK_MANAGER` estiver vazio (freelance).
-
-Registrar conclusão do planejamento:
-
-```
-/eng-global-task-comment {TASK_MANAGER_KEY} ✅ [Jarvis] Planejamento concluído - architecture.md criado. Branch: {NOME_DA_BRANCH}
-```
-
-### 5.5 Finalização
+### 5.4 Finalização
 
 Quando o usuário aprovar, informe:
 

package/workflows/engineering/eng.work.md

@@ -25,7 +25,6 @@ Este comando executa a **implementação de código** seguindo o plano de execu
 |-------|-------|----------|
 | Cabeçalho (agente) | `eng.agent` (agente) | Sempre — identidade do workflow |
 | Fase 0 › 0.1 Verificar ou Gerar Contexto da Sessão | `/jarvis-context-detect` | Se `ENABLE_CDD=true` e o `context.md` não existir (obrigatório antes da Fase 1) |
-| Fase 0.5: Comentário no card — Início | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver preenchido (freelance pula) |
 | Fase 3 › 3.1 Implementar Código (skill de domínio) | `/eng-frontend` (via `eng.specializations-rules.md`) | Se o domínio da feature for frontend (componentes, UI, estado, estilos, bundle, a11y); a regra também carrega `FRONTEND_SPECIALIZATIONS` |
 | Fase 3 › 3.1 Implementar Código (skill de domínio) | `/eng-backend` (via `eng.specializations-rules.md`) | Se o domínio da feature for backend (endpoints, auth, workers, filas, cache, banco, integrações); a regra também carrega `BACKEND_SPECIALIZATIONS` |
 | Fase 3 › 3.1 Implementar Código (skill de domínio) | `/eng-automation` (via `eng.specializations-rules.md`) | Se o domínio da feature for RPA, scraping, extração de dados, ETL ou parsing; a regra também carrega `AUTOMATION_SPECIALIZATIONS` |
@@ -33,7 +32,8 @@ Este comando executa a **implementação de código** seguindo o plano de execu
 | Fase 3 › 3.3.1 Identificar Gaps de Teste | `eng.qa.test-planner` (agente) | Sempre, depois de implementar o código da fase |
 | Fase 3 › 3.3.2 Implementar Testes Faltantes (Opção A) | `eng.qa.testing-engineer` (agente) | Se o test-planner identificar gaps e a estratégia do `architecture.md` seção 6.5 indicar testes manuais (unitário/integração) |
 | Fase 3 › 3.3.2 Implementar Testes Faltantes (Opção B) | `/eng-qa` | Se a estratégia do `architecture.md` seção 6.5 indicar uma especialização registrada em `QA_SPECIALIZATIONS` |
-| Fase 6 › 6.2 Se Todas as Fases Foram Concluídas | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver preenchido e todas as fases estiverem concluídas (freelance pula) |
+| Fase 3 › 3.1 Implementar Código (exceção) | `eng.advisor.agent` (agente) | Só por exceção: questão nova em aberto, com o Advisor habilitado no `eng.start` (cabeçalho do `architecture.md`) |
+| Fase 5 › 5.4 e "Se houver bloqueio técnico" | `/eng-global-task-comment` | Se houver desvio do plano: mudança de direção, fase bloqueada ou questão nova consultada ao Advisor (freelance pula) |
 
 ---
 
@@ -152,20 +152,6 @@ Use as características do projeto detectadas:
 
 ---
 
-## Fase 0.5: Comentário no card — Início
-
-Pular se `TASK_MANAGER` estiver vazio (freelance).
-
-Antes de iniciar a implementação, registrar início:
-
-```
-/eng-global-task-comment {TASK_MANAGER_KEY} ⚙️ [Jarvis] Iniciando implementação - Fase {N} do plano
-```
-
-> Usa o skill `/eng-global-task-comment`. Não bloquear se falhar.
-
----
-
 ## Fase 1: Leitura da Sessão
 
 ### 1.1 Carregar Arquivos
@@ -250,6 +236,8 @@ Para cada tarefa da fase:
    - Testes unitários para cada função/método
    - Cobrir casos de sucesso e erro
 
+**Questão nova em aberto (exceção).** O ideal é que todas as questões tenham sido levantadas no `eng.start`. Se surgir uma nova e o cabeçalho do `architecture.md` indicar um Advisor, consulte `eng.advisor.agent` com o Prompt 2 de `$IDE/templates/engineering/advisor-template.md` (refaça o Prompt 1 se o subagente não existir mais), acrescente a questão à seção 8 marcada "levantada no `eng.work`", adote a sugestão do Advisor e poste o comentário de auditoria com `/eng-global-task-comment` (é desvio do plano; cite-o no PR como lacuna do `eng.start`). Sem Advisor, pergunte ao usuário.
+
 ### 3.2 Executar Validações Locais
 
 Após implementar:
@@ -429,6 +417,8 @@ Atualize o `plan.md`:
 - **Atenção**: {ponto importante para próximas fases}
 ```
 
+Se o comentário registrar uma **mudança de direção** (desvio do plano), comente também no card com `/eng-global-task-comment`, dizendo o que mudou e por quê (freelance pula).
+
 ### 5.3 Commit da Fase (GitFlow)
 
 Após validação do usuário e atualização do `plan.md`, commitar a fase na branch atual:
@@ -494,12 +484,6 @@ Refs: TASK-123"
 
 ### 6.2 Se Todas as Fases Foram Concluídas
 
-**Comentário no card — Conclusão** (pular se freelance):
-
-```
-/eng-global-task-comment {TASK_MANAGER_KEY} ✅ [Jarvis] Implementação concluída - todas as {N} fases completadas. Commits realizados por fase.
-```
-
 ```
 🎉 TODAS AS FASES CONCLUÍDAS!
 
@@ -559,5 +543,6 @@ Refs: TASK-123"
 ### Se houver bloqueio técnico:
 
 → Documente no plan.md como `[Bloqueada 🚫]`
+→ Comente o bloqueio no card com `/eng-global-task-comment` (desvio do plano; freelance pula)
 → Explique o bloqueio ao usuário
 → Sugira alternativas se possível