jarvis-ai-framework 3.0.0 → 4.0.0

package/workflows/engineering/eng.create-ard.md

@@ -3,13 +3,17 @@ description: Fluxo de trabalho de Engenharia para criação/iteração de ARD
 globs:
   alwaysApply: false
   env_file: "@/ENV.md"
-recommended_model: claude-sonnet-4-20250514
+recommended_model: opus
 model_tier: high
 model_justification: Documentação arquitetural requer análise de requisitos, trade-offs técnicos e decisões bem fundamentadas
 ---
 
 # Workflow de Engenharia – ARD (Architecture Requirements Document)
 
+> 🎓 **Modo de condução**: leia `PROD_MODE` no `$IDE/ENV.md`. Se for `developer-guided`, **antes de começar leia `$IDE/rules-on-demand/product/prod.guided-rules.md` e siga-o** em toda a conversa. Vazio ou `product-led`: siga este fluxo como está.
+>
+> 🤖 **Modelo**: se a IDE informar o modelo desta sessão e ele for de outra família que o `recommended_model` do documento (ou do template, se o documento for novo), avise em uma linha e siga, sem bloquear e sem repetir. Sem essa informação, não avise.
+
 ## Objetivo
 
 Guiar o assistente de Engenharia (ENG) na criação, revisão ou iteração de um ARD,
@@ -25,8 +29,8 @@ usando o template `$IDE/templates/engineering/ARD-template.md`, sempre alinhado
 | Passo | Skill | Condição |
 |-------|-------|----------|
 | Objetivo | `eng.agent` (agente) | Sempre — identidade do workflow (alinhamento com `eng.agent.md`) |
-| Passo 1.1.1 – Buscar PRD no Central Docs | `/jarvis-docs-central` (via `jarvis docs sync --silent`) | Se `CENTRAL_DOCS_REPO` estiver definido no ENV.md |
-| Passo 8 – Publicar no Central Docs | `/jarvis-docs-central` (via `jarvis docs publish --tipo ard`) | Se `CENTRAL_DOCS_REPO` estiver definido, o ARD estiver aprovado e o usuário aceitar publicar |
+| Passo 1.1.1 – Buscar PRD no Central Docs | `/jarvis-docs-central` (via `jarvis docs sync --silent`) | Se `CENTRAL_DOCS_STORAGE` estiver definido no ENV.md |
+| Passo 8 – Publicar no Central Docs | `/jarvis-docs-central` (via `jarvis docs publish --tipo ard`) | Se `CENTRAL_DOCS_STORAGE` estiver definido, o ARD estiver aprovado e o usuário aceitar publicar |
 
 ---
 
@@ -64,7 +68,7 @@ usando o template `$IDE/templates/engineering/ARD-template.md`, sempre alinhado
   - Se a pasta `$DOCS_FOLDER/engineering/ARD/` existir e houver arquivos no padrão `ARD-###-*.md`, use o maior `###` + 1.
 - Defina o `ARD-ID` automaticamente assim:
   - Se a pasta `$DOCS_FOLDER/engineering/ARD/` existir e houver arquivos no padrão `ARD-###-*.md`, use o maior `###` + 1.
-- `Status`
+- `Status` (campo `status` no frontmatter: `proposed | in_progress | in_review | approved`)
 - `Caminho do arquivo` (`$DOCS_FOLDER/engineering/ARD/{ARD-ID}-{slug}.md` ou caminho fornecido para iteração)
 
 ---
@@ -109,7 +113,7 @@ Regras:
 3. Confirme os metadados definidos no Passo 0:
    - `ARD-ID`
    - `Título`
-   - `Status`
+   - `Status` (campo `status` no frontmatter)
    - `Caminho do arquivo` (`$DOCS_FOLDER/engineering/ARD/{ARD-ID}-{slug}.md` ou caminho fornecido para iteração)
 
 ---
@@ -118,7 +122,7 @@ Regras:
 
 ### 1.1.1 – Buscar PRD no Central Docs (condicional)
 
-Se `CENTRAL_DOCS_REPO` definido no ENV.md:
+Se `CENTRAL_DOCS_STORAGE` definido no ENV.md:
 
 1. Executar busca automática no central-docs:
    ```bash
@@ -361,7 +365,7 @@ Peça explicitamente para o usuário:
 
 ## Passo 8 – Publicar no Central Docs (condicional)
 
-Se `CENTRAL_DOCS_REPO` definido no ENV.md **E** o usuário aprovar o ARD:
+Se `CENTRAL_DOCS_STORAGE` definido no ENV.md **E** o usuário aprovar o ARD:
 
 1. Perguntar ao usuário:
    ```
@@ -371,20 +375,18 @@ Se `CENTRAL_DOCS_REPO` definido no ENV.md **E** o usuário aprovar o ARD:
    ```
 
 2. Se **Sim**:
-   - Extrair o slug do nome do arquivo (ex: `ARD-001-api-wallet-auth.md` → `api-wallet-auth`)
    - Executar:
      ```bash
      jarvis docs publish \
        --file {caminho_do_ard} \
-       --tipo ard \
-       --feature {slug}
+       --tipo ard
      ```
    
 3. Informar resultado:
-   - ✅ Sucesso: "ARD publicado no central-docs. MR criado: [URL]"
+   - ✅ Sucesso: "ARD publicado no Central docs." (com git: "PR aberto: [URL]")
    - ❌ Erro: Exibir mensagem de erro e orientar troubleshooting
 
 4. Se **Não**:
-   - Informar: "Para publicar depois, execute: `jarvis docs publish --file {caminho} --tipo ard --feature {slug}`"
+   - Informar: "Para publicar depois, execute: `jarvis docs publish --file {caminho} --tipo ard`"
 
-> **Nota**: A publicação cria um Merge Request no GitLab. O ARD só será visível no central-docs após aprovação e merge do MR.
+> **Nota**: se a pasta do Central docs for um repositório git, a publicação abre um Pull/Merge Request e o ARD só entra na branch base depois do merge. Sem git, o documento é gravado direto e o índice é regenerado.

package/workflows/engineering/eng.create-rfc.md

@@ -27,8 +27,8 @@ Além disso, quando houver campo `Versão` no RFC, aplicar obrigatoriamente:
 
 | Passo | Skill | Condição |
 |-------|-------|----------|
-| Passo 0.6 – Buscar Documentação Relacionada no Central Docs | `/jarvis-docs-central` (via `jarvis docs sync --silent`) | Se `CENTRAL_DOCS_REPO` estiver definido no ENV.md |
-| Passo 7 – Publicar no Central Docs | `/jarvis-docs-central` (via `jarvis docs publish --tipo rfc`) | Se `CENTRAL_DOCS_REPO` estiver definido **e** o usuário aprovar o RFC e responder "Sim, publicar agora" |
+| Passo 0.6 – Buscar Documentação Relacionada no Central Docs | `/jarvis-docs-central` (via `jarvis docs sync --silent`) | Se `CENTRAL_DOCS_STORAGE` estiver definido no ENV.md |
+| Passo 7 – Publicar no Central Docs | `/jarvis-docs-central` (via `jarvis docs publish --tipo rfc`) | Se `CENTRAL_DOCS_STORAGE` estiver definido **e** o usuário aprovar o RFC e responder "Sim, publicar agora" |
 
 ---
 
@@ -92,7 +92,7 @@ Regras:
 
 ## Passo 0.6 – Buscar Documentação Relacionada no Central Docs (condicional)
 
-Se `CENTRAL_DOCS_REPO` definido no ENV.md:
+Se `CENTRAL_DOCS_STORAGE` definido no ENV.md:
 
 1. Executar busca automática no central-docs:
    ```bash
@@ -223,7 +223,7 @@ Entregar:
 
 ## Passo 7 – Publicar no Central Docs (condicional)
 
-Se `CENTRAL_DOCS_REPO` definido no ENV.md **E** o usuário aprovar o RFC:
+Se `CENTRAL_DOCS_STORAGE` definido no ENV.md **E** o usuário aprovar o RFC:
 
 1. Perguntar ao usuário:
    ```
@@ -233,20 +233,18 @@ Se `CENTRAL_DOCS_REPO` definido no ENV.md **E** o usuário aprovar o RFC:
    ```
 
 2. Se **Sim**:
-   - Extrair o slug do nome do arquivo (ex: `RFC-001-wallet-idempotencia.md` → `wallet-idempotencia`)
    - Executar:
      ```bash
      jarvis docs publish \
        --file {caminho_do_rfc} \
-       --tipo rfc \
-       --feature {slug}
+       --tipo rfc
      ```
    
 3. Informar resultado:
-   - ✅ Sucesso: "RFC publicado no central-docs. MR criado: [URL]"
+   - ✅ Sucesso: "RFC publicado no Central docs." (com git: "PR aberto: [URL]")
    - ❌ Erro: Exibir mensagem de erro e orientar troubleshooting
 
 4. Se **Não**:
-   - Informar: "Para publicar depois, execute: `jarvis docs publish --file {caminho} --tipo rfc --feature {slug}`"
+   - Informar: "Para publicar depois, execute: `jarvis docs publish --file {caminho} --tipo rfc`"
 
-> **Nota**: A publicação cria um Merge Request no GitLab. O RFC só será visível no central-docs após aprovação e merge do MR.
+> **Nota**: se a pasta do Central docs for um repositório git, a publicação abre um Pull/Merge Request e o RFC só entra na branch base depois do merge. Sem git, o documento é gravado direto e o índice é regenerado.

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) |
 
 ---
 
@@ -62,25 +61,11 @@ Ler `TASK_MANAGER` do `$IDE/ENV.md`. Seguir `$IDE/rules/engineering/eng.integrat
 - `TASK_MANAGER` vazio → *Qual o seu número de controle para esta tarefa? (ex: F-042)*
 - `TASK_MANAGER` preenchido → *Qual o id do card no {TASK_MANAGER}?*
 
-> A branch de destino **padrão é `dev`** (GitFlow). Só perguntar se o usuário indicar outra branch (ex: hotfix direto para `main`).
+> A branch de destino é a **`Branch base:`** gravada no cabeçalho do `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/architecture.md` pelo `eng.start`. Só perguntar (`main`, `dev` ou Outro) se o campo não existir.
 > 💡 A branch de feature já foi criada no `eng.start`. Este workflow apenas faz push e abre o MR.
 
 ---
 
-## 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
@@ -137,7 +122,7 @@ A branch deve seguir o padrão `{TASK_MANAGER_KEY}-{titulo-em-kebab-case}`.
 
 ### 2.2 Confirmar Branch de Destino
 
-Branch de destino padrão: **`dev`** (GitFlow).
+Branch de destino: a **`Branch base:`** do `architecture.md` (`{BRANCH_BASE}`). Sem o campo, pergunte com `AskUserQuestion` (`main`, `dev` ou Outro); não presuma.
 
 > ⚠️ **Nunca fazer push direto para `main` ou `master`** sem confirmação explícita do usuário.
 
@@ -152,7 +137,7 @@ git checkout {TASK_MANAGER_KEY}-{titulo-em-kebab-case}
 ### 2.2 Verificar Commits da Branch
 
 ```bash
-git log dev..HEAD --oneline
+git log {BRANCH_BASE}..HEAD --oneline
 ```
 
 Deve listar os commits das fases implementadas no `eng.work`.
@@ -218,7 +203,7 @@ Preencher com a tarefa. Link do card:
 
 - **Título**: `{TASK_MANAGER_KEY}: {Título da tarefa}`
 - **Branch origem**: `{NOME_DA_BRANCH}`
-- **Branch destino**: a informada pelo usuário (`dev` / `main` / hotfix)
+- **Branch destino**: `{BRANCH_BASE}` (a `Branch base:` do `architecture.md`)
 - **Descrição**: template preenchido, gravado em arquivo temporário
 
 ```bash
@@ -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,8 +40,7 @@ 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 |
+| Gate 0: Verificar Documentação Central | `/jarvis-docs-central` (via `jarvis docs publish --tipo ard`) | Se `CENTRAL_DOCS_STORAGE` 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 |
 | Gates › item 3 | `eng.qa.test-planner` (agente) | Sempre — identificar gaps de cobertura de testes na branch |
@@ -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
 
@@ -80,7 +65,7 @@ Ao iniciar o pre-PR, registrar:
 
 ### Gate 0: Verificar Documentação Central (condicional)
 
-Se `CENTRAL_DOCS_REPO` estiver configurado no ENV.md:
+Se `CENTRAL_DOCS_STORAGE` estiver configurado no ENV.md:
 
 **Passo 1:** Detectar mudanças arquiteturais no diff da branch
 ```bash
@@ -92,14 +77,14 @@ git diff main...HEAD | grep -E "(class|interface|schema|migration|config)" || tr
 - Comparar com ARD do central-docs (se existir)
 - Se desatualizado ou novo:
   - Perguntar: "Publicar ARD atualizado no central-docs?"
-  - Se sim: executar `jarvis docs publish --file <path> --tipo ard --feature <slug>`
+  - Se sim: executar `jarvis docs publish --file <path> --tipo ard`
 
 **Passo 3:** Se novos contratos/APIs criados:
 - Verificar se há RFC relacionado
 - Se não: sugerir criar RFC para decisões arquiteturais
 
 **Comportamento:**
-- Se `CENTRAL_DOCS_REPO` vazio → pular silenciosamente
+- Se `CENTRAL_DOCS_STORAGE` vazio → pular silenciosamente
 - Não bloquear PR por docs desatualizados (apenas avisar)
 
 ---
@@ -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.rpa.robot.md

@@ -75,14 +75,16 @@ grep "^ENABLE_CDD=" $IDE/ENV.md
 
 ### 0.3 Criar Branch e Sessão
 
+Pergunte a branch base com `AskUserQuestion` (**"De qual branch partir?"**: `main`, `dev`, `{branch atual}` se for outra, ou Outro) e grave `Branch base:` no `architecture.md` da sessão; o `eng.pr` abre o PR para ela.
+
 ```bash
-git checkout dev && git pull origin dev
+git checkout {BRANCH_BASE} && git pull --ff-only origin {BRANCH_BASE}
 git checkout -b {TASK_MANAGER_KEY}-{robot-tag}
 mkdir -p $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/
 echo "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" > $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/.timestamp_start
 ```
 
-> Branch sempre criada a partir de `dev`. Nunca de `main`/`master`.
+> A base é sempre perguntada: não presuma `dev` nem `main`. A branch de trabalho nunca é a própria base.
 
 ---
 

package/workflows/engineering/eng.start.md

@@ -26,8 +26,8 @@ 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 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 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_STORAGE` 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) |
 | Fase 3.4: Estratégia de Testes | `/eng-ai` | Se a feature envolver IA (LLM, RAG, agentes, chatbots, embeddings) |
@@ -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,30 +123,28 @@ 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).
+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.
 
-Após obter o `TASK_MANAGER_KEY`, registrar o início do planejamento:
+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.
 
-```
-/eng-global-task-comment {TASK_MANAGER_KEY} 🚀 [Jarvis] Iniciando planejamento - architecture.md sendo criado
-```
-
-> 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).
 
 ---
 
 ## Fase 1: Preparação do Ambiente
 
-### 1.1 Criar Branch de Feature (GitFlow)
+### 1.1 Criar Branch de Feature
+
+**Pergunte sempre a branch base** com `AskUserQuestion` (sem a ferramenta, use a tabela de `prod-rules.md`): **"De qual branch partir?"** com as opções `main`, `dev` e `{branch atual}` (só se a branch atual for outra), mais "Outro" para digitar. Não presuma `dev` nem `main`: cada projeto tem o seu fluxo.
 
-Crie a branch de trabalho a partir de `dev` seguindo o padrão GitFlow:
+Grave a escolha no cabeçalho do `architecture.md` (`Branch base:`). O `eng.pr` abre o PR para essa mesma branch.
 
 ```bash
-# Garantir que está em dev e atualizado
-git checkout dev
-git pull origin dev
+# Garantir que a base está atualizada
+git checkout {BRANCH_BASE}
+git pull --ff-only origin {BRANCH_BASE}
 
 # Criar branch no padrão {TASK_MANAGER_KEY}-{titulo-em-kebab-case}
 git checkout -b {TASK_MANAGER_KEY}-{titulo-em-kebab-case}
@@ -179,9 +177,9 @@ git branch --show-current
 | `TASK-123` | "Implementar autenticação JWT" | `TASK-123-implementar-autenticacao-jwt` |
 | `BUG-789` | "Fix null pointer em login" | `BUG-789-fix-null-pointer-em-login` |
 
-> ⚠️ Se o usuário já estiver em uma branch com o padrão correto do TASK_MANAGER_KEY, use-a sem criar nova.
-> ⚠️ **NUNCA** criar branch a partir de `main`/`master`. Sempre a partir de `dev`.
-> ✅ A branch criada aqui será usada em todos os workflows subsequentes (work, pre-pr, pr).
+> ⚠️ Se o usuário já estiver em uma branch com o padrão correto do TASK_MANAGER_KEY, use-a sem criar nova (e ainda assim pergunte a base, para o `eng.pr`).
+> ⚠️ Se o projeto tiver convenção própria de nome de branch (ex.: `CONTRIBUTING.md`), siga a do projeto.
+> ✅ A branch criada aqui será usada em todos os workflows subsequentes (work, pre-pr, pr). Ela é sempre uma branch de trabalho: nunca implemente direto na base.
 
 ### 1.2 Criar Diretório de Sessão
 
@@ -219,7 +217,7 @@ Solicite ao usuário os dados de entrada:
 
 ### 2.2 Buscar Documentação Central (condicional)
 
-Se `CENTRAL_DOCS_REPO` estiver configurado no ENV.md, buscar docs relacionados:
+Se `CENTRAL_DOCS_STORAGE` estiver configurado no ENV.md, buscar docs relacionados:
 
 **Passo 1:** Identificar docs relevantes com base no Jira ID e tags do card
 
@@ -234,7 +232,7 @@ Se `CENTRAL_DOCS_REPO` estiver configurado no ENV.md, buscar docs relacionados:
 **Comportamento:**
 - Se docs encontrados → carregar e exibir resumo
 - Se não encontrados → perguntar se tem docs localmente
-- Se `CENTRAL_DOCS_REPO` vazio → pular silenciosamente
+- Se `CENTRAL_DOCS_STORAGE` vazio → pular silenciosamente
 
 ### 2.3 Análise do Requisito
 
@@ -382,6 +380,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,39 +413,30 @@ 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:
 
 ```
 ✅ Architecture.md criado com sucesso!
 
-🌿 Branch: {TASK_MANAGER_KEY}-{titulo-em-kebab-case} (criada a partir de dev)
+🌿 Branch: {NOME_DA_BRANCH} (criada a partir de {BRANCH_BASE})
 📄 Arquivo: $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/architecture.md
-🌿 Branch:  {NOME_DA_BRANCH}
 
 🔄 Board: mova o card para "Em progresso" no seu board de tarefas.
 
 📌 Próximos passos:
 1. Execute `eng.plan` para criar o plano detalhado de execução
 2. Execute `eng.work` para implementar (commita automaticamente ao final de cada fase)
-3. Execute `eng.pr` para abrir o MR para dev
+3. Execute `eng.pr` para abrir o MR para {BRANCH_BASE}
 
 🚫 Lembre-se: Este workflow NÃO executa código.
    Para implementar, use os comandos de execução.
@@ -452,11 +453,11 @@ Quando o usuário aprovar, informe:
 - ❌ NÃO faça commits
 - ❌ NÃO instale dependências
 - ❌ NÃO modifique arquivos de código existentes
-- ❌ NÃO crie branch a partir de `main`/`master`
+- ❌ NÃO crie a branch sem perguntar a base
 
 ### ✅ FAÇA APENAS
 
-- ✅ Criar branch a partir de `dev` no padrão `{TASK_MANAGER_KEY}-{titulo}`
+- ✅ Criar branch a partir da base escolhida pelo usuário, no padrão `{TASK_MANAGER_KEY}-{titulo}`
 - ✅ Criar o diretório `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/`
 - ✅ Criar o arquivo `architecture.md`
 - ✅ Investigar e analisar o codebase (leitura apenas)