jarvis-ai-framework 4.0.0 → 5.0.0

package/workflows/engineering/eng.pr.md

@@ -1,5 +1,5 @@
 ---
-description: Criação de branch, commit e merge request (MR)
+description: Gera o pull-request.md na sessão e, com o Sim do usuário, faz o push e abre o merge request (MR)
 auto_execution_mode: 3
 agent: "$IDE/agents/engineering/eng.agent.md"
 rules_file: "$IDE/rules-on-demand/engineering/eng.pr-rules.md"
@@ -43,8 +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 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 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) |
+| Fase 4 › 4.4 Criar MR/PR via adapter | `jarvis vcs create-merge` (CLI do Jarvis) | Só se o usuário responder **Sim** na Fase 4.3: abre o MR/PR conforme `VERSION_CONTROL` ou o host do `origin` |
+| Fase 6 › 6.2 Link do MR | `/eng-global-task-comment` | Depois de o MR ser criado (só com o Sim da 4.3): um único comentário no card com o link do MR, seguindo o Passo 6 do skill `eng-global-pr` (freelance pula) |
 
 ---
 
@@ -156,6 +156,8 @@ Refs: {TASK_MANAGER_KEY}"
 
 ## Fase 3: Push
 
+> ⚠️ O push só acontece **depois do Sim** da Fase 4.3. Esta fase descreve o comando; ele roda dentro da publicação.
+
 ### 3.1 Enviar para Remote
 
 ```bash
@@ -175,7 +177,9 @@ git log --oneline -3
 Ler `VERSION_CONTROL` do `$IDE/ENV.md` (`gitlab` | `github` | `bitbucket`).
 Use **MR** se GitLab, **PR** se GitHub/Bitbucket.
 
-### 4.1 Preparar descrição
+### 4.1 Gerar `pull-request.md` na sessão
+
+Escreva o título e a descrição do PR em **`$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/pull-request.md`** (primeira linha `# {título}`, depois o corpo). Se a sessão tiver o `gate-checklist.md` do `eng.pre-pr`, use o PR Brief e as decisões dele.
 
 Template, nesta ordem (o primeiro que existir):
 
@@ -199,21 +203,32 @@ Preencher com a tarefa. Link do card:
 
 > ⚠️ Não mencione AI, Claude ou assistentes no MR/PR.
 
-### 4.2 Criar MR/PR via adapter
+### 4.2 Revisão do texto
+
+Mostre o `pull-request.md` (título e resumo das seções) e pergunte com `AskUserQuestion`: `[Aprovar]` / `[Ajustar]`. Ajuste até a aprovação.
+
+### 4.3 Publicar? (Sim / Não)
+
+Pergunte com `AskUserQuestion` (**Sim / Não**): **"Publicar o PR agora?"**
+
+- **Não:** nada é enviado. O `pull-request.md` fica na sessão para você publicar quando quiser (à mão ou rodando o `/eng.pr` de novo). Pule para a Fase 7, com a mensagem "PR não publicado".
+- **Sim:** faça o push (Fase 3) e crie o MR/PR (4.4).
+
+### 4.4 Criar MR/PR via adapter
 
 - **Título**: `{TASK_MANAGER_KEY}: {Título da tarefa}`
 - **Branch origem**: `{NOME_DA_BRANCH}`
 - **Branch destino**: `{BRANCH_BASE}` (a `Branch base:` do `architecture.md`)
-- **Descrição**: template preenchido, gravado em arquivo temporário
+- **Descrição**: o corpo do `pull-request.md` aprovado (sem a linha do título)
 
 ```bash
 BODY_FILE=$(mktemp)
-# gravar a descrição preenchida em $BODY_FILE
+tail -n +2 $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/pull-request.md > "$BODY_FILE"
 
 jarvis vcs create-merge \
   --source "${NOME_DA_BRANCH}" \
-  --target "${TARGET_BRANCH}" \
-  --title "${TASK_MANAGER_KEY}: ${TITULO_DA_TAREFA}" \
+  --target "${BRANCH_BASE}" \
+  --title "${TITULO_DO_PULL_REQUEST_MD}" \
   --body-file "$BODY_FILE"
 
 rm -f "$BODY_FILE"
@@ -326,65 +341,18 @@ fi
 {LEAD_TIME_MSG}
 
 📌 Próximos passos:
-1. Aguardar revisão do time
-2. Processar comentários do code review
+1. /eng.spec-consolidate {TASK_MANAGER_KEY} → registrar no Central docs o que esta entrega implementou
+2. Aguardar revisão do time e processar os comentários do code review
 3. Merge após aprovação
 
+🗂️ A sessão $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/ não é apagada (o /eng.spec-consolidate precisa dela).
+   Remova à mão quando quiser.
+
 🔗 Links:
 - MR: {LINK_DO_MR}
 - Jira: {TASK_MANAGER_URL_BASE}/browse/{TASK_MANAGER_KEY}
 ```
 
-## Fase 8: Limpeza da Sessão
-
-### 9.1 Solicitar Confirmação
-
-Após o MR ser criado com sucesso, **solicitar confirmação do usuário**:
-
-```
-🧹 Deseja limpar a sessão?
-
-A pasta $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/ será removida.
-A documentação permanece no Jira e no MR.
-
-Confirmar? (s/n)
-```
-
-> ⚠️ **IMPORTANTE**: Sempre pedir confirmação antes de executar comandos destrutivos.
-
-### 9.2 Remover Pasta da Sessão
-
-Se confirmado:
-
-```bash
-rm -rf $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/
-```
-
-**Exemplo:**
-
-```bash
-rm -rf $SESSIONS_DIR/eng/task-123/
-```
-
-### 9.3 Confirmar Limpeza
-
-```
-🧹 SESSÃO LIMPA!
-
-📁 Removido: $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/
-   - architecture.md ✅
-   - plan.md ✅
-   - context.md ✅ (se existia)
-
-ℹ️ A documentação permanece no:
-   - Card do Jira: {TASK_MANAGER_KEY}
-   - Merge Request: {LINK_DO_MR}
-```
-
-> ⚠️ **NOTA**: A documentação não é perdida! Ela está anexada no Jira e registrada no MR.
-
----
-
 ## Regras Importantes
 
 ### ⛔ NÃO FAÇA
@@ -403,7 +371,8 @@ rm -rf $SESSIONS_DIR/eng/task-123/
 - ✅ Criar branch no padrão `{TASK_MANAGER_KEY}-{titulo}`
 - ✅ Preencher template do MR completamente
 - ✅ Mover card para "In Review"
-- ✅ **Limpar sessão após criar MR** (`rm -rf $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/`)
+- ✅ Gerar o `pull-request.md` na sessão e só publicar com o **Sim** (Fase 4.3)
+- ✅ **Nunca apagar a sessão:** o `/eng.spec-consolidate` precisa dela
 
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-description: Validação de segurança para realizar um pull request ou merge request
+description: Revisão de lacunas antes de abrir o PR/MR, com o relatório gate-checklist.md na sessão
 auto_execution_mode: 3
 env_file: "@/ENV.md"
 rules_file: "$IDE/rules-on-demand/engineering/eng.pre-pr-rules.md"
@@ -10,7 +10,9 @@ model_justification: Revisão multi-agente requer coordenação, análise de có
 
 # pre-pr
 
-Estamos nos aproximando de finalizar o trabalho nesta branch e nos preparar para um solicitação de integração. Agora, é hora de fazer verificações finais e limpezas para assegurar que estamos alinhados com nossos convenções e objetivos.
+Antes de abrir o PR/MR, este comando **revê a branch atrás de possíveis lacunas** (produto, código, testes, requisitos não funcionais, interface, segurança, documentação) e gera um relatório, o **`gate-checklist.md`**, na pasta da sessão. Ele é estruturado e explicativo, para você decidir o que ajustar e o que não ajustar.
+
+> ⚠️ **Só revisa.** O `eng.pre-pr` não corrige código, não escreve testes, não atualiza documentação e não publica nada no Central docs. Ele aponta; quem decide e ajusta é você (ou o `eng.work`, se pedir).
 
 > 📋 **Rules**: `$IDE/rules-on-demand/engineering/eng.pre-pr-rules.md` — **antes de começar, leia esse arquivo e siga-o**: ele não é carregado automaticamente no início da sessão.
 
@@ -18,7 +20,7 @@ Estamos nos aproximando de finalizar o trabalho nesta branch e nos preparar para
 
 - **eng-qa-planner**: para avaliar cobertura de testes e identificar gaps antes do PR — se a especialização estiver registrada em `QA_SPECIALIZATIONS` (ver `$IDE/rules/engineering/eng.specializations-rules.md`). Sem ela, use a base `eng-qa` diretamente.
   - Arquivo: `$IDE/skills/eng-qa-planner/SKILL.md`
-- **eng-global-docs-write**: para atualizar documentação baseada nas mudanças da branch.
+- **eng-global-docs-write**: para identificar documentação que ficou desatualizada com as mudanças da branch.
   - Arquivo: `$IDE/skills/eng-global-docs-write/SKILL.md`
 - **jarvis-docs-index**: para atualizar o índice de documentação quando necessário.
   - Arquivo: `$IDE/skills/jarvis-docs-index/SKILL.md`
@@ -36,117 +38,78 @@ Estamos nos aproximando de finalizar o trabalho nesta branch e nos preparar para
 | Passo | Skill | Condição |
 |-------|-------|----------|
 | Skills recomendados | `/eng-qa-planner` | Se a especialização estiver registrada em `QA_SPECIALIZATIONS`; sem ela, usar a base `/eng-qa` diretamente |
-| Skills recomendados | `/eng-global-docs-write` | Para atualizar a documentação com base nas mudanças da branch |
+| Skills recomendados | `/eng-global-docs-write` | Para identificar documentação desatualizada pelas mudanças da branch |
 | 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 |
-| 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 |
-| Gates › item 4 | `eng.qa.testing-engineer` (agente) | Se o test-planner identificar gaps críticos (escrever os testes faltantes) |
 | Gates › item 5 | `eng.qa.test-architect` (agente) | Se a feature tiver requisitos não-funcionais (no `architecture.md` ou explícitos na task) |
 | Gates › item 6 | `/eng-qa` + `QA_SPECIALIZATIONS` | Sempre — frontend e/ou backend conforme o projeto |
 | Gates › item 7 | `eng.frontend.agent` (agente) | Se a branch tiver mudanças de interface (componentes, estilos, estado) |
 | 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 9 | `eng.docs-writer` (agente) | Sempre — apontar documentação do projeto desatualizada (sem editar) |
 | 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 |
-| 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) |
+| Publicação do relatório | `/eng-global-task-comment` | Só se o usuário responder **Sim** no fim: o `gate-checklist.md` com as decisões vira um comentário na issue/card (freelance pula) |
 
 ## Regras de Execução
 
-- **Escopo**: avalie apenas as mudanças desta branch em relação ao branch base (ex.: `main`/`master`).
-- **Evidências**: sempre que mencionar “testes/validações passando”, inclua quais comandos foram usados e o resultado (ou descreva smoke tests manuais quando não houver suíte).
-- **Revalidação**: se qualquer gate levar a mudanças no código, reexecute no mínimo:
-  - Gate 2 (revisão técnica)
-  - Gate 3 (testes/validações)
+- **Escopo**: avalie apenas as mudanças desta branch em relação à **branch base** (`Branch base:` do `architecture.md`; sem ele, pergunte).
+- **Só apontar**: cada agente/gate devolve lacunas, não correções. Nenhum arquivo do projeto é alterado por este comando.
+- **Evidências**: cite o comando rodado e o resultado, ou `arquivo:linha`, para cada lacuna.
 
-## Gates
+## Gates (revisão)
 
-### Gate 0: Verificar Documentação Central (condicional)
+1. Invoque o agente [prod.pm-checker]($IDE/agents/product/prod.pm-checker.md) para apontar desalinhamentos entre a branch e os documentos de produto e de engenharia (em `$PROD_DOCS`, `$ENG_DOCS` e no Central docs).
+2. Invoque o agente [eng.dev-code-reviewer]($IDE/agents/engineering/eng.dev-code-reviewer.md) para apontar problemas de código (bugs, legibilidade, padrões do projeto).
+3. Invoque o agente [eng.qa.test-planner]($IDE/agents/engineering/qa/eng.qa.test-planner.md) para apontar lacunas de cobertura de testes. Lacunas críticas: funções públicas sem teste, lógica de negócio descoberta, tratamento de erro não validado.
+4. **Se a feature tiver requisitos não funcionais** (no `architecture.md` ou explícitos na task), invoque o agente [eng.qa.test-architect]($IDE/agents/engineering/qa/eng.qa.test-architect.md) para apontar o que falta validar (performance, segurança, quality gates).
+5. Use a base [eng-qa]($IDE/skills/eng-qa/SKILL.md) (ou a especialização registrada em `QA_SPECIALIZATIONS`) para rodar os testes automatizados da branch e registrar o resultado.
+6. **Se a branch tiver mudanças de interface**, invoque o agente [eng.frontend.agent]($IDE/agents/engineering/eng.frontend.agent.md) para apontar problemas de tipagem, tokens de design e acessibilidade (WCAG 2.1 AA), aplicando as especializações de frontend registradas.
+7. **Se a branch introduzir nova feature de UI ou alterar fluxo de usuário**, invoque o agente [eng.ux-designer.agent]($IDE/agents/engineering/eng.ux-designer.agent.md) para apontar empty states, loading, mensagens de erro e consistência visual.
+8. **Se a branch tocar em auth, sessions, inputs de usuário, CORS, CSP, permissões ou adicionar endpoints públicos**, aplique o checklist de segurança (padrões da base [eng-backend]($IDE/skills/eng-backend/SKILL.md) + `BACKEND_SPECIALIZATIONS`, [eng-frontend]($IDE/skills/eng-frontend/SKILL.md) + `FRONTEND_SPECIALIZATIONS` e, para infraestrutura, [eng-platform]($IDE/skills/eng-platform/SKILL.md) + `PLATFORM_SPECIALIZATIONS`): sanitização de inputs e queries parametrizadas, auth guards, headers e CORS, secrets no diff, `npm audit` sem HIGH/CRITICAL.
+9. Invoque o agente [eng.docs-writer]($IDE/agents/engineering/eng.docs-writer.md) para apontar documentação do projeto que ficou desatualizada (sem editar).
 
-Se `CENTRAL_DOCS_STORAGE` estiver configurado no ENV.md:
+## Relatório: `gate-checklist.md` (obrigatório)
 
-**Passo 1:** Detectar mudanças arquiteturais no diff da branch
-```bash
-git diff main...HEAD | grep -E "(class|interface|schema|migration|config)" || true
-```
+Grave em `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/gate-checklist.md`:
 
-**Passo 2:** Se mudanças arquiteturais detectadas:
-- Verificar se ARD local existe em `./docs/engineering/`
-- 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`
+```markdown
+# Gate checklist — {TASK_MANAGER_KEY}
 
-**Passo 3:** Se novos contratos/APIs criados:
-- Verificar se há RFC relacionado
-- Se não: sugerir criar RFC para decisões arquiteturais
+> Branch: {branch} → {branch base} · Data: {AAAA-MM-DD}
+> **Semáforo:** 🟢 pronto para PR | 🟡 pode abrir com notas | 🔴 há bloqueadores
 
-**Comportamento:**
-- Se `CENTRAL_DOCS_STORAGE` vazio → pular silenciosamente
-- Não bloquear PR por docs desatualizados (apenas avisar)
+## Resumo
+{3 a 5 frases: o que a branch faz, quantas lacunas por severidade e o principal risco.}
 
----
+## Lacunas
+
+### {Área: Produto e documentação | Código | Testes | Não funcionais | Interface e UX | Segurança | Documentação do projeto}
+
+| # | Lacuna | Onde | Por que importa | Sugestão | Severidade | Decisão |
+|---|---|---|---|---|---|---|
+| 1 | {o que falta ou está errado} | `{arquivo:linha}` | {impacto, em linguagem simples} | {como resolver} | 🔴 Bloqueador / 🟡 Importante / ⚪ Menor | {Ajustar \| Não ajustar: motivo} |
 
-1. Invoque o agente [prod.pm-checker]($IDE/agents/product/prod.pm-checker.md) para verificar se a branch está alinhada com os docs do projeto, documentação de produto e de engenharia.
-2. Invoque o agente [eng.dev-code-reviewer]($IDE/agents/engineering/eng.dev-code-reviewer.md) para revisar o código e assegurar que está bom para lançar.
-3. Invoque o agente [eng.qa.test-planner]($IDE/agents/engineering/qa/eng.qa.test-planner.md) para identificar gaps de cobertura de testes na branch.
-4. **Se o test-planner identificar gaps críticos**, invoque o agente [eng.qa.testing-engineer]($IDE/agents/engineering/qa/eng.qa.testing-engineer.md) para escrever os testes faltantes antes de prosseguir.
-   - Gaps críticos: funções públicas sem teste, lógica de negócio descoberta, tratamento de erros não validado
-   - Gaps aceitáveis (com justificativa): código de infraestrutura, integrações já cobertas por e2e
-5. **Se a feature tiver requisitos não-funcionais** (definidos no `architecture.md` ou explícitos na task), invoque o agente [eng.qa.test-architect]($IDE/agents/engineering/qa/eng.qa.test-architect.md) para validar:
-   - Testes de performance executados e dentro dos thresholds
-   - Testes de segurança passando (RBAC, injection, etc.)
-   - Quality gates configurados corretamente
-6. Use a base [eng-qa]($IDE/skills/eng-qa/SKILL.md) (ou a especialização registrada em `QA_SPECIALIZATIONS`, se houver uma) para validar testes automatizados nas mudanças da branch, frontend e/ou backend conforme o projeto.
-7. **Se a branch tiver mudanças de interface** (componentes, estilos, estado), invoque o agente [eng.frontend.agent]($IDE/agents/engineering/eng.frontend.agent.md) para validar:
-   - Tipagem forte (quando a linguagem tem), tokens de design do projeto usados, acessibilidade WCAG 2.1 AA
-   - Aplicar as exigências das especializações de frontend registradas (ver `eng.specializations-rules.md`)
-8. **Se a branch introduzir nova feature de UI ou alterar fluxo de usuário**, invoque o agente [eng.ux-designer.agent]($IDE/agents/engineering/eng.ux-designer.agent.md) para verificar:
-   - Empty states, loading states e mensagens de erro em linguagem humana
-   - Consistência com padrões visuais existentes no produto
-9. Invoque o agente [eng.docs-writer]($IDE/agents/engineering/eng.docs-writer.md) para atualizar a documentação do projeto.
-10. **Se a branch tocar em auth, sessions, inputs de usuário, CORS, CSP, permissões ou adicionar endpoints públicos**, aplicar o gate de segurança (os padrões de segurança da base [eng-backend]($IDE/skills/eng-backend/SKILL.md) + `BACKEND_SPECIALIZATIONS` / [eng-frontend]($IDE/skills/eng-frontend/SKILL.md) + `FRONTEND_SPECIALIZATIONS` e, para infraestrutura, do [eng-platform]($IDE/skills/eng-platform/SKILL.md) + `PLATFORM_SPECIALIZATIONS` servem de referência):
-   - Revisar sanitização de inputs e queries parametrizadas
-   - Verificar auth guards em endpoints novos
-   - Validar headers de segurança e configurações de CORS
-   - Escanear secrets no diff (`grep` por patterns de tokens/senhas)
-   - Verificar `npm audit` sem vulnerabilidades HIGH/CRITICAL
-   - Se achados CRITICAL: status **Red** (bloqueador)
-
-Você também precisará lidar com todo o feedback que esses agentes fornecerem e fazer mudanças e correções conforme necessário.
-
-## Checklist final (obrigatório)
-
-- [ ] Não existem bloqueadores abertos (segurança/bugs críticos).
-- [ ] Testes e validações relevantes foram executados e passaram (com evidências automatizadas ou manuais).
-- [ ] Cobertura de testes para mudanças da branch foi avaliada (e gaps críticos tratados ou justificados).
-- [ ] Documentação foi revisada/atualizada (listar arquivos alterados) ou foi explicitado por que não foi necessário.
-- [ ] Riscos conhecidos e trade-offs foram registrados (e follow-ups criados quando aplicável).
-
-## Saída final (obrigatória)
-
-### 1) Status Pre-PR (Semáforo)
-
-- Green: pronto para PR
-- Yellow: pode abrir PR com notas e follow-ups
-- Red: não pode abrir PR (listar bloqueadores)
-
-### 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):
-
-### 3) PR Brief (para colar no PR)
+(uma tabela por área; área sem lacuna: "Nenhuma lacuna encontrada.")
 
+## Evidências
+{Comandos rodados (testes, lint, build, audit) e resultados.}
+
+## PR Brief
 - Resumo do que mudou:
 - Como testar:
-- Evidências de testes/validações:
-- Docs atualizadas:
 - Riscos / trade-offs:
+```
+
+A coluna **Decisão** nasce vazia: quem preenche é o usuário.
+
+## Fechamento
 
-Uma vez terminado, me avise e peça minha permissão para abrir o Pull Request.
+1. Mostre o semáforo, o resumo e a lista de lacunas por severidade, com o caminho do `gate-checklist.md`.
+2. Peça as decisões: para cada lacuna 🔴 e 🟡, "Ajustar" ou "Não ajustar" (com o motivo). Use `AskUserQuestion` por lacuna quando houver poucas; com muitas, deixe a pessoa responder em texto ou editar o arquivo. Grave as decisões na coluna **Decisão**.
+3. Pergunte com `AskUserQuestion` (**Sim / Não**, sempre, nunca publicar sem a resposta): **"Publicar o gate-checklist.md (com as decisões) como comentário na issue/card?"**
+   - **Sim** (e `TASK_MANAGER` preenchido): `/eng-global-task-comment {TASK_MANAGER_KEY}` com o conteúdo do arquivo.
+   - **Não**, ou modo freelance: fica só na sessão.
+4. Próximo passo: ajustar o que foi marcado "Ajustar" (à mão ou com o `/eng.work`) e rodar o `/eng.pr`, que usa o PR Brief deste relatório.

package/workflows/engineering/eng.rpa.robot.md

@@ -47,7 +47,7 @@ Formato esperado: `new {TASK_MANAGER_KEY}` ou `update {TASK_MANAGER_KEY}`
 3. **[se `new`]** Qual o tag do serviço? (ex: `consulta-orgao`, `extrator-dados`) — será usado como `{robot-tag}`
 4. **[se `update`]** Qual robô será mantido? Listar opções:
    ```bash
-   ls docs/engineering/robots/
+   ls $ENG_DOCS/robots/
    ```
    Apresentar a lista e pedir que o dev escolha.
 
@@ -204,7 +204,7 @@ Garantir durante a implementação:
 
 ### Fase N4 — Documentação
 
-Criar `docs/engineering/robots/{robot-tag}-robot.md`.
+Criar `$ENG_DOCS/robots/{robot-tag}-robot.md`.
 
 Seguir `$IDE/rules/engineering/eng.docs-scraping-rules.md`:
 
@@ -239,7 +239,7 @@ No corpo do PR incluir: link para `{robot-tag}-robot.md`, variáveis de ambiente
 Ler o documento existente do robô:
 
 ```bash
-cat docs/engineering/robots/{robot-tag}-robot.md
+cat $ENG_DOCS/robots/{robot-tag}-robot.md
 ```
 
 Extrair e apresentar ao usuário:
@@ -304,7 +304,7 @@ Para bug fixes estruturais (seletor quebrado, campo mudou de posição):
 
 ### Fase U4 — Atualizar Documentação
 
-Atualizar `docs/engineering/robots/{robot-tag}-robot.md`:
+Atualizar `$ENG_DOCS/robots/{robot-tag}-robot.md`:
 
 - **Sempre**: Histórico de Bugs (toda correção estrutural entra aqui com referência ao card)
 - **Se campos mudaram**: atualizar Fontes de Dados e Campos Extraídos
@@ -331,7 +331,7 @@ Chamar `/jarvis-docs-index` após atualizar.
   Modo     : {new | update}
   Robô     : {robot-tag}-robot
   Classe   : {RobotTag}Robot
-  Docs     : docs/engineering/robots/{robot-tag}-robot.md
+  Docs     : $ENG_DOCS/robots/{robot-tag}-robot.md
   Branch   : {TASK_MANAGER_KEY}-{robot-tag}
   PR       : (link do MR criado pelo eng.pr)
 ─────────────────────────────────────────────────────────────

package/workflows/engineering/eng.spec-consolidate.md

@@ -0,0 +1,140 @@
+---
+description: Consolida o que a entrega implementou no Central docs (documento da funcionalidade + registro da entrega)
+auto_execution_mode: 3
+agent: "$IDE/agents/engineering/eng.docs-consolidator.agent.md"
+template_file: "$IDE/templates/engineering/central-feature-template.md"
+recommended_model: opus
+model_tier: high
+model_justification: Consolidar exige ler e cruzar muitas fontes (documentos, decisões, diff e commits) e escrever um registro completo e sem ambiguidade
+---
+
+# Consolidar no Central docs
+
+Este comando registra no **Central docs** o que a entrega **de fato implementou**. Ele roda **logo depois do PR aberto** (`/eng.pr`) e gera dois documentos completos e autossuficientes:
+- o **documento da funcionalidade** (`feature-{slug}.md`), com o estado atual, novo ou atualizado;
+- o **registro da entrega** (`delivery-{AAAA-MM-DD}-{task_key}.md`), com o PR, os commits e os autores.
+
+Os documentos de trabalho (PRD, FRD, ARD, RFC…) continuam em `docs/jarvis/` e **não** vão para o Central docs: lá fica só o que foi implementado.
+
+> 🤖 **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 for novo), avise em uma linha e siga, sem bloquear e sem repetir. Sem essa informação, não avise.
+> 📤 **Templates**: `$IDE/templates/engineering/central-feature-template.md` e `$IDE/templates/engineering/central-delivery-template.md`
+
+### Skills invocados durante o workflow
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| Cabeçalho (agente) | `eng.docs-consolidator.agent` (agente) | Sempre: escreve a consolidação na sessão |
+| Passo 3 (funcionalidade) e Passo 6 (publicação) | `/jarvis-docs-central` (via `jarvis docs fetch` / `jarvis docs publish`) | Sempre: lê o índice e o documento atual e publica depois do Sim |
+
+---
+
+## Entrada
+
+<arguments>
+#$ARGUMENTS
+</arguments>
+
+- `{TASK_MANAGER_KEY}` (obrigatório no modo normal): a mesma chave do `eng.start`/`eng.pr`. Sem ela, pergunte e aguarde (`eng.integrations-rules.md`; no modo freelance, o número de controle).
+- `{slug}` (opcional): slug da funcionalidade, se você já souber qual atualizar.
+- `--inicial`: carga inicial a partir dos documentos de trabalho que já existem (chamado pelo `/jarvis-init`). Não precisa de chave nem de PR.
+
+---
+
+## Passo 0: Pré-condições
+
+1. **Central docs ligado:** `CENTRAL_DOCS_STORAGE` preenchido no `$IDE/ENV.md`. Se estiver vazio, pare: "O Central docs está desligado. Ligue-o no `/jarvis-init` (Passo 5.2) para registrar o que foi implementado."
+2. **Modo normal:** a sessão `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/` existe com o `architecture.md`. Sem ela, avise que a consolidação perde as decisões e pergunte se segue só com o diff e os documentos de trabalho.
+3. **Branch base:** o `Branch base:` do `architecture.md`. Sem ele, pergunte com `AskUserQuestion` (`main`, `dev` ou Outro).
+
+## Passo 1: Coleta (modo normal)
+
+O agente `eng.docs-consolidator` lê **todas** as fontes, na ordem do agente:
+1. `architecture.md` e `plan.md` da sessão.
+2. Documentos de trabalho ligados à tarefa em `$PROD_DOCS` e `$ENG_DOCS` (PRD, FRD, épicos, histórias, ARD, RFC, swagger, QA).
+3. Commits e arquivos:
+   ```bash
+   git log {base}..HEAD --format='%h|%an|%ad|%s' --date=short
+   git diff --stat {base}...HEAD
+   ```
+4. **PR/MR:** número e URL (`pull-request.md` da sessão, `gh pr view`/equivalente do vendor, ou pergunte).
+5. **Card:** URL no padrão do `TASK_MANAGER` (`eng.integrations-rules.md`); no modo freelance, só o número de controle.
+6. `gate-checklist.md` e `pull-request.md` da sessão, se existirem.
+
+## Passo 2: Coleta (modo `--inicial`)
+
+1. Liste os PRD, FRD, ARD e RFC em `$PROD_DOCS` e `$ENG_DOCS/{ARD,RFC}` (e nos caminhos antigos, se o `/jarvis-init` não os moveu).
+2. Sugira o agrupamento por funcionalidade (um PRD/FRD e os ARD/RFC ligados a ele) e confirme com `AskUserQuestion` (aceitar / ajustar).
+3. Para cada grupo, o agente lê os documentos e o código relacionado (só leitura), para descrever o que **está implementado**. O que estiver só especificado vai para "Fora do escopo", e o status reflete isso.
+
+## Passo 3: Qual funcionalidade
+
+1. `jarvis docs fetch {SQUAD}/index.md` e liste as funcionalidades existentes do produto (`WORKSPACE`).
+2. Sugira uma, pelo PRD/FRD de origem, pelo título do `architecture.md` e pelos arquivos do diff, e um slug novo bem nomeado (kebab-case, pelo nome que o negócio usa).
+3. Pergunte com `AskUserQuestion`:
+   - "Atualizar `feature-{x}`" (sugerida);
+   - "Criar `feature-{slug sugerido}`";
+   - Outro (digitar).
+
+   Se o slug veio como argumento, confirme com a mesma pergunta.
+4. Na atualização, `jarvis docs fetch {SQUAD}/product/{produto}/feature-{x}.md` é o ponto de partida.
+
+## Passo 4: Escrever na sessão
+
+O agente gera em `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/consolidation/` (no `--inicial`, em `$SESSIONS_DIR/eng/inicial-{AAAA-MM-DD}/consolidation/`):
+- `feature-{slug}.md`: todas as 11 seções do template, com o estado atual e a linha nova no Histórico de entregas;
+- `delivery-{AAAA-MM-DD}-{task_key}.md`: as 7 seções (não existe no `--inicial`).
+
+O frontmatter segue o template, com os comentários `#`. `product` = `WORKSPACE` (ou o produto confirmado).
+
+## Passo 5: Revisão
+
+Mostre o resumo dos dois arquivos (seções, tamanho, referências) e o caminho deles. Pergunte com `AskUserQuestion`:
+- `[Aprovar]`
+- `[Ajustar]`: diga o que mudar; o agente ajusta e você revisa de novo.
+
+Confira antes de aprovar:
+- [ ] card e PR/MR com URL;
+- [ ] commits com autor (sem e-mail);
+- [ ] nenhum segredo nem valor de variável;
+- [ ] nenhuma frase depende de um documento de origem.
+
+## Passo 6: Publicar
+
+Pergunte com `AskUserQuestion` (**Sim / Não**): **"Publicar no Central docs?"**
+
+- **Sim:**
+  ```bash
+  jarvis docs publish --file .../consolidation/delivery-{AAAA-MM-DD}-{task_key}.md --tipo delivery
+  jarvis docs publish --file .../consolidation/feature-{slug}.md --tipo feature
+  ```
+  (no `--inicial`, só os `feature-*`). Com o Central docs num repositório git, cada publicação abre um PR no repositório de documentação: informe as URLs.
+- **Não:** os arquivos ficam na sessão. Para publicar depois, use os mesmos comandos.
+
+## Passo 7: Mensagem final
+
+```
+✅ Consolidação {publicada | salva na sessão}
+
+📄 Funcionalidade: {SQUAD}/product/{produto}/feature-{slug}.md
+🧾 Entrega:        {SQUAD}/engineering/{produto}/delivery-{AAAA-MM-DD}-{task_key}.md
+🔗 PR/MR: {URL} · Card: {URL ou número}
+
+🧹 A sessão $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/ não é apagada automaticamente: remova à mão quando quiser.
+```
+
+---
+
+## Regras
+
+### ⛔ Nunca
+- Publicar sem o **Sim** do Passo 6
+- Publicar PRD, FRD, ARD ou RFC no Central docs (só `feature` e `delivery`)
+- Incluir e-mails, tokens, senhas, valores de variáveis ou dados pessoais de clientes
+- Inventar informação: sem fonte, pergunte ou registre "não informado"
+- Alterar o código, os documentos de trabalho ou a sessão fora de `consolidation/`
+
+### ✅ Sempre
+- Ler todas as fontes antes de escrever
+- Citar o card e o PR/MR com URL (ou o número de controle no freelance)
+- Descrever o implementado, não o pretendido
+- Português do Brasil

package/workflows/engineering/eng.start.md

@@ -221,17 +221,17 @@ Se `CENTRAL_DOCS_STORAGE` estiver configurado no ENV.md, buscar docs relacionado
 
 **Passo 1:** Identificar docs relevantes com base no Jira ID e tags do card
 
-**Passo 2:** Buscar documentos via skill jarvis-docs-central:
-- PRD relacionado (contexto de produto)
-- ARD geral do produto (arquitetura macro)
-- ARD específico do repo (se existir)
-- RFCs relevantes
+**Passo 2:** Buscar via skill jarvis-docs-central **o que já foi implementado**:
+- funcionalidades relacionadas (`feature-*`): comportamento atual, decisões, onde está no código;
+- entregas recentes dessas funcionalidades (`delivery-*`), se ajudarem.
+
+Os documentos de trabalho da tarefa (PRD, FRD, ARD, RFC) ficam em `$PROD_DOCS`/`$ENG_DOCS` (`docs/jarvis/`): leia-os de lá.
 
 **Passo 3:** Incorporar ao contexto antes de prosseguir para análise
 
 **Comportamento:**
 - Se docs encontrados → carregar e exibir resumo
-- Se não encontrados → perguntar se tem docs localmente
+- Se não encontrados → seguir com os documentos de trabalho em `docs/jarvis/` e o card
 - Se `CENTRAL_DOCS_STORAGE` vazio → pular silenciosamente
 
 ### 2.3 Análise do Requisito

package/workflows/engineering/eng.work.md

@@ -264,7 +264,7 @@ Invoque o agente [eng.qa.test-planner]($IDE/agents/engineering/qa/eng.qa.test-pl
 - Analisar o código implementado na fase
 - Identificar funções/métodos sem cobertura de teste
 - Mapear casos de borda não cobertos
-- Gerar relatório de gaps em `$DOCS_FOLDER/engineering/qa/{task-id}-test_coverage_branch_report.md`
+- Gerar relatório de gaps em `$ENG_DOCS/qa/{task-id}-test_coverage_branch_report.md`
 
 #### 3.3.2 Implementar Testes Faltantes
 

package/workflows/engineering/qa/eng.qa-refinement-entry.md

@@ -67,7 +67,7 @@ O código ainda não existe neste momento do fluxo.
 ## Output
 
 Documento de estratégia de testes salvo em:
-`$DOCS_FOLDER/engineering/qa/strategies/{task-id}-test-strategy.md`
+`$ENG_DOCS/qa/strategies/{task-id}-test-strategy.md`
 
 Estrutura do documento:
 ```

package/workflows/engineering/qa/eng.qa-release-signoff.md

@@ -63,7 +63,7 @@ Verificar se foi realizada sessão para a feature.
 
 **3. Quality gate**
 ```bash
-ls $DOCS_FOLDER/engineering/qa/ 2>/dev/null | grep -i "quality-gate\|qg"
+ls $ENG_DOCS/qa/ 2>/dev/null | grep -i "quality-gate\|qg"
 ```
 Verificar se a spec passou pelo quality gate antes da sprint.
 
@@ -102,7 +102,7 @@ Usar template `$TEMPLATES_FOLDER/engineering/qa/qa.release-signoff-template.md`.
 
 Salvar em:
 ```
-$DOCS_FOLDER/engineering/qa/signoffs/signoff-{branch-slug}-{YYYYMMDD}.md
+$ENG_DOCS/qa/signoffs/signoff-{branch-slug}-{YYYYMMDD}.md
 ```
 
 > O frontmatter **deve** conter `status: GO` ou `status: NO-GO` — o CLI `jarvis qa-signoff` lê este campo.
@@ -172,5 +172,5 @@ Se $MESSAGE_COMUNICATOR não estiver configurado ou o TL não tiver Slack ID em
 
 ## Output
 
-- `$DOCS_FOLDER/engineering/qa/signoffs/signoff-{branch-slug}-{YYYYMMDD}.md` — documento de sign-off
+- `$ENG_DOCS/qa/signoffs/signoff-{branch-slug}-{YYYYMMDD}.md` — documento de sign-off
 - Snippet CI (apenas na primeira execução, se pipeline ainda não configurado)

package/workflows/engineering/qa/eng.qa-sprint-planning.md

@@ -93,7 +93,7 @@ Com base no risco e na capacidade mapeada na Fase 0:
 Usando o template `$TEMPLATES_FOLDER/engineering/qa/qa.sprint-plan-template.md`, gerar o plano e salvar em:
 
 ```
-$DOCS_FOLDER/engineering/qa/sprints/sprint-plan-{sprint-slug}.md
+$ENG_DOCS/qa/sprints/sprint-plan-{sprint-slug}.md
 ```
 
 Exibir o plano ao usuário e perguntar se há ajustes antes de salvar.
@@ -102,5 +102,5 @@ Exibir o plano ao usuário e perguntar se há ajustes antes de salvar.
 
 ## Output
 
-- `$DOCS_FOLDER/engineering/qa/sprints/sprint-plan-{sprint-slug}.md` — plano de alocação da sprint
+- `$ENG_DOCS/qa/sprints/sprint-plan-{sprint-slug}.md` — plano de alocação da sprint
 - Pronto para compartilhar com o time ou colar no $TASK_MANAGER