jarvis-ai-framework 8.1.0 → 8.2.0

package/README.md

@@ -100,7 +100,9 @@ npm install -g jarvis-ai-framework@latest
 jarvis init --upgrade --ide {ide}   # assets + variáveis novas do ENV.md + documentos para as pastas novas
 ```
 
-Depois, na IDE, rode `/jarvis-init upgrade`: ele vai direto ao Upgrade (C) e cuida do que precisa de conversa (Central docs antigo e o passo das stacks). O `--upgrade` só **acrescenta** chaves ao `ENV.md`: nenhuma chave existente muda. Ele mostra os documentos que estão em caminhos antigos e pergunta antes de movê-los (`--yes` move sem perguntar; sem terminal interativo, não move). Também lista os skills instalados que saíram do framework e pergunta antes de removê-los (`--remove-stale` remove sem perguntar só os listados; skills registrados em `*_SPECIALIZATIONS` nunca são listados).
+`jarvis init --ide {ide}` numa pasta já instalada mostra o menu **Atualizar** (Enter, o mesmo que o `--upgrade`) / **Reinstalar** (o mesmo que o `--force`) / **Cancelar**, com a versão instalada e a do pacote. No fim, ele só manda rodar o `/jarvis-init upgrade` quando há pendência.
+
+Na IDE, o `/jarvis-init upgrade` vai direto ao Upgrade (C), cuida do que precisa de conversa (Central docs antigo e o passo das stacks) e, no fim, valida o `ENV.md` inteiro: pergunta cada problema e regrava o arquivo separado por assunto, na ordem do template. O `--upgrade` só **acrescenta** chaves ao `ENV.md`, no fim do arquivo: nenhuma chave existente muda. Ele mostra os documentos que estão em caminhos antigos e pergunta antes de movê-los (`--yes` move sem perguntar; sem terminal interativo, não move). Também lista os skills instalados que saíram do framework e pergunta antes de removê-los (`--remove-stale` remove sem perguntar só os listados; skills registrados em `*_SPECIALIZATIONS` nunca são listados).
 
 **Instalou via clone local** (fluxo de [Desenvolvendo o Jarvis localmente](#desenvolvendo-o-jarvis-localmente)) — quando o repo no GitHub ganhar commits novos, sincronize assim:
 

package/agents/engineering/eng.agent.md

@@ -175,20 +175,26 @@ Para detecção automática de contexto de tarefas:
 - Uso: `/jarvis-context-detect [jira-key]` ou `/jarvis-context-detect --override tipo=hotfix`
 - Chamado automaticamente pelo workflow `eng.start`
 
-### eng-platform (performance)
-Quando a tarefa envolver análise ou otimização de performance, observabilidade, gargalos, latência, load testing, chaos engineering ou cache multi-camada — temas 7, 14, 15 e 16 da base de platform:
+### eng-platform
+Quando a tarefa envolver infraestrutura, performance ou segurança de infraestrutura — base de platform, complementada pela especialização registrada em `PLATFORM_SPECIALIZATIONS`:
 - Arquivo: `$IDE/skills/eng-platform/SKILL.md`
+- Performance: análise ou otimização de performance, observabilidade, gargalos, latência, load testing, chaos engineering ou cache multi-camada (temas 7, 14, 15 e 16)
+- Segurança: segurança de infraestrutura, fundamentos de segurança da informação (risco, ameaças, identidade, resposta a incidente, GRC, privacidade) ou auditoria de dependências/supply chain (temas 9 e 13)
+- Segurança de código de aplicação (OWASP, inputs, auth) já é padrão embutido em `eng-backend`/`eng-frontend`
 
 ### eng-ai
 Quando a tarefa envolver features com LLM, sistemas RAG, agentes de IA, chatbots, embeddings, busca vetorial ou integrações com modelos de IA:
 - Arquivo: `$IDE/skills/eng-ai/SKILL.md`
 
-### Backend e frontend (skill base + especializações)
-Quando a tarefa envolver **backend** (APIs, autenticação, workers e jobs assíncronos, filas e mensageria, integrações externas, cache, banco de dados) ou **frontend** (componentes, estado, estilos, performance de UI, acessibilidade, testes de interface), não escolha o skill por nome: aplique a regra `$IDE/rules/engineering/eng.specializations-rules.md` para a área envolvida. Ela carrega o skill base e as especializações que o projeto registrou no `ENV.md`:
-- Backend: `$IDE/skills/eng-backend/SKILL.md` + itens de `BACKEND_SPECIALIZATIONS`
-- Frontend: `$IDE/skills/eng-frontend/SKILL.md` + itens de `FRONTEND_SPECIALIZATIONS`
+### eng-backend
+Quando a tarefa envolver backend (APIs, autenticação, workers e jobs assíncronos, filas e mensageria, integrações externas, cache, banco de dados). Não escolha o skill por nome: aplique a regra `$IDE/rules/engineering/eng.specializations-rules.md` para a área backend, que carrega o skill base e as especializações de `BACKEND_SPECIALIZATIONS` do `ENV.md`:
+- Arquivo: `$IDE/skills/eng-backend/SKILL.md`
 - Workflows relacionados: `eng.start` (arquitetura), `eng.work` (implementação), `eng.debug` (troubleshooting)
-- Para ver o que está instalado e registrado: `/jarvis-list-specializations`
+
+### eng-frontend
+Quando a tarefa envolver frontend (componentes, estado, estilos, performance de UI, acessibilidade, testes de interface). Não escolha o skill por nome: aplique a regra `$IDE/rules/engineering/eng.specializations-rules.md` para a área frontend, que carrega o skill base e as especializações de `FRONTEND_SPECIALIZATIONS` do `ENV.md`:
+- Arquivo: `$IDE/skills/eng-frontend/SKILL.md`
+- Para ver o que está instalado e registrado (backend e frontend): `/jarvis-list-specializations`
 
 ### eng-automation
 Quando a tarefa envolver web scraping, extração de dados de páginas web, automação de browser com Puppeteer, parsing de HTML/XML/PDF, pipelines ETL leves ou monitoramento de mudanças em sites:
@@ -200,10 +206,6 @@ Quando precisar planejar estratégia de testes, validar fluxos completos de usu
 - Arquivo: `$IDE/skills/eng-qa/SKILL.md`
 - Workflows relacionados: `eng.pr` (validação pré-PR), `eng.pre-pr` (cobertura de testes E2E)
 
-### eng-platform
-Quando a tarefa envolver segurança de infraestrutura, fundamentos de segurança da informação (risco, ameaças, identidade, resposta a incidente, GRC, privacidade) ou auditoria de dependências/supply chain — base de platform, complementada pela especialização registrada em `PLATFORM_SPECIALIZATIONS`:
-- Arquivo: `$IDE/skills/eng-platform/SKILL.md` (temas 9 e 13)
-- Segurança de código de aplicação (OWASP, inputs, auth) já é padrão embutido em `eng-backend`/`eng-frontend`
 
 ---
 

package/agents/engineering/eng.dev-code-reviewer.md

@@ -6,18 +6,18 @@ model: opus
 color: green
 ---
 
-# code-reviewe
+# code-reviewer
 Você é um especialista em revisão de código responsável por analisar mudanças de código em preparação para a abertura de um Pull Request.
 Seu objetivo é fornecer feedback abrangente e acionável, ajudando a garantir qualidade de código e prontidão para PR.
 
 Processo de Revisão
 1. Coleta de Informações sobre as Mudanças
-Primeiro, entenda exatamente o que foi alterado:
+Primeiro, entenda exatamente o que foi alterado (`{BRANCH_BASE}` é a branch base recebida de quem chama (o `/eng.pre-pr` passa a `Branch base:` do `architecture.md`); sem ela, `origin/main`.):
  - Execute git status para verificar mudanças não commitadas
  - Execute git diff para visualizar mudanças não staged
  - Execute git diff --staged para visualizar mudanças staged
- - Execute git log origin/main..HEAD --oneline para ver os commits da branch atual
- - Execute git diff origin/main...HEAD para ver todas as mudanças comparadas com a branch principal
+ - Execute git log {BRANCH_BASE}..HEAD --oneline para ver os commits da branch atual
+ - Execute git diff {BRANCH_BASE}...HEAD para ver todas as mudanças comparadas com a branch base
 
 2. Análise das Mudanças de Código
 Para cada arquivo alterado, avalie:
@@ -71,6 +71,21 @@ Avalie os testes:
 
 Nenhuma — agente autocontido, não depende de skill
 
+## Quando chamado pelo `/eng.pre-pr`
+
+O `/eng.pre-pr` passa a branch base (a `Branch base:` do `architecture.md`) e, da rodada 2 em diante, o diff incremental desde a rodada anterior. Use essa base no lugar de `origin/main` nos comandos de diff e log. Só aponte: não edite nem grave arquivos.
+
+Devolva uma lista de lacunas, uma por item, com os campos da tabela de lacunas do `gate-checklist.md`:
+
+- **Lacuna**: o que falta ou está errado, terminando com "(item 2)", o número deste gate na lista do `/eng.pre-pr`.
+- **Onde**: `arquivo:linha` com o trecho, ou o comando que a revelou e o resultado.
+- **Por que importa**: o impacto, em linguagem simples.
+- **Refutação**: o que derrubaria esta lacuna, com o lugar a conferir.
+- **Sugestão**: como resolver.
+- **Severidade**: 🔴 Bloqueador, 🟡 Importante ou ⚪ Menor (redação é ⚪).
+
+Lista vazia é uma resposta válida. Fora do `/eng.pre-pr`, vale o formato de resposta deste arquivo.
+
 ## Formato da Resposta
 Forneça uma revisão estruturada no seguinte formato:
 

package/agents/engineering/eng.docs-writer.md

@@ -17,6 +17,21 @@ Fonte de verdade do processo e do formato de entrega da documentação:
 
 ---
 
+## Quando chamado pelo `/eng.pre-pr`
+
+O `/eng.pre-pr` passa a branch base (a `Branch base:` do `architecture.md`) e, da rodada 2 em diante, o diff incremental desde a rodada anterior. Use essa base no lugar de `origin/main` nos comandos de diff e log. Só aponte: não edite nem grave arquivos. Não proponha aplicar as atualizações nem pergunte se deve aplicá-las: cada documentação desatualizada vira uma lacuna.
+
+Devolva uma lista de lacunas, uma por item, com os campos da tabela de lacunas do `gate-checklist.md`:
+
+- **Lacuna**: o que falta ou está errado, terminando com "(item 9)", o número deste gate na lista do `/eng.pre-pr`.
+- **Onde**: `arquivo:linha` com o trecho, ou o comando que a revelou e o resultado.
+- **Por que importa**: o impacto, em linguagem simples.
+- **Refutação**: o que derrubaria esta lacuna, com o lugar a conferir.
+- **Sugestão**: como resolver.
+- **Severidade**: 🔴 Bloqueador, 🟡 Importante ou ⚪ Menor (redação é ⚪).
+
+Lista vazia é uma resposta válida. Fora do `/eng.pre-pr`, vale o formato de resposta deste arquivo.
+
 ## Fluxo de Trabalho
 
 ### 1. Analisar Mudanças de Código
@@ -26,8 +41,8 @@ Comece entendendo exatamente o que mudou:
 - Execute `git status` para verificar mudanças não commitadas
 - Execute `git diff` para visualizar mudanças não staged
 - Execute `git diff --staged` para visualizar mudanças staged
-- Execute `git log origin/main..HEAD --oneline` para ver os commits da branch
-- Execute `git diff origin/main...HEAD` para ver todas as mudanças da branch
+- Execute `git log {BRANCH_BASE}..HEAD --oneline` para ver os commits da branch
+- Execute `git diff {BRANCH_BASE}...HEAD` para ver todas as mudanças da branch (`{BRANCH_BASE}` é a branch base recebida de quem chama (o `/eng.pre-pr` passa a `Branch base:` do `architecture.md`); sem ela, `origin/main`.)
 
 Foque especialmente em:
 - Novas funcionalidades

package/agents/engineering/qa/eng.qa.test-planner.md

@@ -21,10 +21,25 @@ Aplicar quando invocado via `eng.qa-refinement-entry` ou quando o argumento rece
 
 **Modo B — Análise de Cobertura (pós-código)**
 Aplicar quando invocado via `eng-qa`, `eng-qa-planner` ou quando houver código implementado na branch (git diff retorna resultados).
-- Fonte de dados: `git diff origin/main...HEAD`
+- Fonte de dados: `git diff {BRANCH_BASE}...HEAD` (`{BRANCH_BASE}` é a branch base recebida de quem chama (o `/eng.pre-pr` passa a `Branch base:` do `architecture.md`); sem ela, `origin/main`.)
 - Saída: `$ENG_DOCS/qa/{task-id}-test_coverage_branch_report.md`
 
-Regra de decisão: se `git diff origin/main...HEAD` retornar vazio, operar em Modo A. Se retornar código, operar em Modo B.
+Regra de decisão: se `git diff {BRANCH_BASE}...HEAD` retornar vazio, operar em Modo A. Se retornar código, operar em Modo B.
+
+## Quando chamado pelo `/eng.pre-pr`
+
+O `/eng.pre-pr` passa a branch base (a `Branch base:` do `architecture.md`) e, da rodada 2 em diante, o diff incremental desde a rodada anterior. Use essa base no lugar de `origin/main` nos comandos de diff e log. Só aponte: não edite nem grave arquivos. É o Modo B, mas sem gravar o relatório em `$ENG_DOCS/qa/`: as lacunas voltam só na resposta.
+
+Devolva uma lista de lacunas, uma por item, com os campos da tabela de lacunas do `gate-checklist.md`:
+
+- **Lacuna**: o que falta ou está errado, terminando com "(item 3)", o número deste gate na lista do `/eng.pre-pr`.
+- **Onde**: `arquivo:linha` com o trecho, ou o comando que a revelou e o resultado.
+- **Por que importa**: o impacto, em linguagem simples.
+- **Refutação**: o que derrubaria esta lacuna, com o lugar a conferir.
+- **Sugestão**: como resolver.
+- **Severidade**: 🔴 Bloqueador, 🟡 Importante ou ⚪ Menor (redação é ⚪).
+
+Lista vazia é uma resposta válida. Fora do `/eng.pre-pr`, vale o formato de resposta deste arquivo.
 
 ## Skills Disponíveis
 
@@ -290,9 +305,9 @@ Usar quando: invocado via `eng-qa` ou `eng-qa-planner`, ou quando git diff retor
 
 Comece entendendo o que mudou na branch atual:
 
-- Execute `git diff origin/main...HEAD --name-only` para listar todos os arquivos alterados
-- Execute `git diff origin/main...HEAD` para ver as mudanças em detalhe
-- Execute `git log origin/main..HEAD --oneline` para entender o histórico de commits
+- Execute `git diff {BRANCH_BASE}...HEAD --name-only` para listar todos os arquivos alterados
+- Execute `git diff {BRANCH_BASE}...HEAD` para ver as mudanças em detalhe
+- Execute `git log {BRANCH_BASE}..HEAD --oneline` para entender o histórico de commits
 - Foque especialmente em:
   - Novas funções/métodos/classes
   - Lógica modificada em código existente

package/agents/product/prod.pm-checker.md

@@ -28,7 +28,7 @@ Em seguida, você deve:
   - quais mudanças não estão alinhadas.
 
 Formato da Resposta
-Você deve fornecer sua resposta exatamente no seguinte formato:
+Você deve fornecer sua resposta exatamente no seguinte formato (quando chamado pelo `/eng.pre-pr`, use o formato da seção "Quando chamado pelo `/eng.pre-pr`"):
 
 ```
 [nome da branch]
@@ -51,6 +51,21 @@ Você deve fornecer sua resposta exatamente no seguinte formato:
 Regras Importantes
 Não faça nenhuma alteração no código ou nos requisitos, a menos que o usuário solicite explicitamente. Seu papel é avaliar e reportar, não corrigir.
 
+## Quando chamado pelo `/eng.pre-pr`
+
+O `/eng.pre-pr` passa a branch base (a `Branch base:` do `architecture.md`) e, da rodada 2 em diante, o diff incremental desde a rodada anterior. Use essa base no lugar de `origin/main` nos comandos de diff e log. Só aponte: não edite nem grave arquivos. Compare as mudanças com os documentos do projeto (os "Master Docs") como descrito acima.
+
+Devolva uma lista de lacunas, uma por item, com os campos da tabela de lacunas do `gate-checklist.md`:
+
+- **Lacuna**: o que falta ou está errado, terminando com "(item 1)", o número deste gate na lista do `/eng.pre-pr`.
+- **Onde**: `arquivo:linha` com o trecho, ou o comando que a revelou e o resultado.
+- **Por que importa**: o impacto, em linguagem simples.
+- **Refutação**: o que derrubaria esta lacuna, com o lugar a conferir.
+- **Sugestão**: como resolver.
+- **Severidade**: 🔴 Bloqueador, 🟡 Importante ou ⚪ Menor (redação é ⚪).
+
+Lista vazia é uma resposta válida. Fora do `/eng.pre-pr`, vale o formato de resposta deste arquivo.
+
 ## Skills Disponíveis
 
 Nenhuma — agente autocontido, não depende de skill

package/bin/README.md

@@ -124,7 +124,7 @@ if (fileURLToPath(import.meta.url) === process.argv[1]) {
 ## Testes
 
 - `npm run test:comandos` — valida que toda referência a comando/skill nos workflows e skills existe de fato (não testa o CLI em runtime).
-- `npm run test:filtro` — testes unitários de `profile-filter.js`, `token-report.js`, `flow-map`, `env-loader.js`, `sync-engine.js`, `vcs/api.js`, `tasks/comment.js`, `integrations/` (catálogo e runner) e do upgrade.
+- `npm run test:filtro` — testes unitários de `profile-filter.js`, `token-report.js`, `flow-map`, `env-loader.js`, `sync-engine.js`, `vcs/api.js`, `tasks/comment.js`, `integrations/` (catálogo e runner) e do upgrade, além dos testes que guardam o texto de workflows e rules (por exemplo, `gate-checklist-rodadas`, `publish-comments-rules` e `pre-pr-criterio`). A lista completa é o script `test:filtro` do `package.json`.
 - Não há teste automatizado de ponta a ponta do CLI (`jarvis <comando>` real) — a camada de dispatch (`program.js`, `bin/commands/*.js`) não é cobrida pelos testes unitários. Qualquer mudança ali precisa de validação manual dos comandos afetados.
 
 ### Como testar código que lê `fs`/rede sem mockar módulo

package/bin/commands/init.js

@@ -39,6 +39,115 @@ function ask(rl, question) {
   return new Promise((resolve) => rl.question(question, resolve));
 }
 
+/**
+ * Escolha do menu de pasta já instalada (#189). Função pura, para testar sem subprocesso.
+ * Com ENV.md: Enter ou 1 = atualizar (a opção recomendada), 2 = reinstalar, 3 = cancelar.
+ * Sem ENV.md não há o que atualizar (o upgrade precisa dele): o menu só tem 2 e 3, e Enter
+ * cancela, para o padrão nunca ser destrutivo (Q3). Qualquer outra resposta é inválida (Q9).
+ * @param {string} answer - linha digitada
+ * @param {{ hasEnv: boolean }} opts
+ * @returns {"upgrade" | "reinstall" | "cancel" | null} `null` = resposta inválida
+ */
+export function parseMenuChoice(answer, { hasEnv }) {
+  const choice = String(answer).trim();
+  if (choice === "2") return "reinstall";
+  if (choice === "3") return "cancel";
+  if (hasEnv && (choice === "" || choice === "1")) return "upgrade";
+  if (!hasEnv && choice === "") return "cancel";
+  return null;
+}
+
+/**
+ * O que ainda pede o `/jarvis-init upgrade` na IDE depois do `jarvis init --upgrade` (#189, Q4).
+ * Só as pendências que o terminal não resolve: eixo sem forma de acesso, chave vazia, Central docs
+ * no formato antigo e TOKEN_TASK_MANAGER com valor. Não contam o aviso de WORKSPACE_MODE (conferir
+ * no ENV.md), vendor não suportado (vira freelance) nem as chaves novas acrescentadas (Q15: o
+ * `/jarvis-init` as põe no assunto delas na próxima vez que rodar). Nunca inclui valores do ENV.
+ * @param {{ pendingAxes: string[], envPlan: { pending?: string[], warnings?: string[] } }} input
+ * @returns {string[]} um motivo por pendência; vazio = nada pendente
+ */
+export function upgradePendencies({ pendingAxes, envPlan }) {
+  const reasons = [];
+  if (pendingAxes.length) reasons.push(`confirmar o acesso de ${pendingAxes.join(" e ")}`);
+  if (envPlan.pending?.length) reasons.push(`preencher ${envPlan.pending.join(", ")}`);
+  const warnings = envPlan.warnings || [];
+  if (warnings.includes("CENTRAL_DOCS_REPO")) reasons.push("migrar o Central docs");
+  if (warnings.includes("TOKEN_TASK_MANAGER")) reasons.push("remover o TOKEN_TASK_MANAGER");
+  return reasons;
+}
+
+/**
+ * Leitor de linhas que não perde resposta: guarda as linhas que chegam antes da pergunta
+ * (pipe com várias linhas, como `printf 's\n3\n'`) e devolve `null` quando a entrada fecha
+ * sem linha (CI com `</dev/null`), em vez de esperar para sempre como o `rl.question` (Q2).
+ * @param {import("node:readline").Interface} rl
+ * @returns {(question: string) => Promise<string | null>}
+ */
+function lineReader(rl) {
+  const lines = [];
+  const waiting = [];
+  let closed = false;
+  rl.on("line", (line) => (waiting.length ? waiting.shift()(line) : lines.push(line)));
+  rl.on("close", () => {
+    closed = true;
+    while (waiting.length) waiting.shift()(null);
+  });
+  // Sem terminal, a resposta não aparece na tela: a quebra de linha separa a pergunta do que vem depois.
+  const echo = (line) => {
+    if (line !== null && !process.stdin.isTTY) process.stdout.write("\n");
+    return line;
+  };
+  return (question) => {
+    process.stdout.write(question);
+    if (lines.length) return Promise.resolve(echo(lines.shift()));
+    if (closed) return Promise.resolve(null);
+    return new Promise((resolve) => waiting.push(resolve)).then(echo);
+  };
+}
+
+/**
+ * Menu de `jarvis init` numa pasta que já tem a pasta da IDE (#189).
+ * Decide pela resposta lida, não por `process.stdin.isTTY`: `printf '\n' |` também atualiza.
+ * `askLine` é o leitor compartilhado com o menu de IDE: um leitor só para a entrada inteira,
+ * para a resposta de um menu não consumir a do outro (`printf '1\n3\n' | jarvis init`).
+ * @returns {Promise<"upgrade" | "reinstall" | "cancel" | "no-answer">} `no-answer` = entrada fechada (a mensagem já saiu)
+ */
+async function askInstalledMenu({ folder, lockVersion, packageVersion, hasEnv, askLine }) {
+  const installed = lockVersion === "desconhecida" ? "versão desconhecida" : `v${lockVersion}`;
+  logger.info(
+    `${YELLOW}⚠️  Jarvis já instalado em .${folder} (${installed} · pacote v${packageVersion})${NC}`
+  );
+  logger.info("");
+  if (!hasEnv) {
+    logger.info(`${DIM}Atualizar precisa do ENV.md: reinstale e rode /jarvis-init na IDE.${NC}`);
+    logger.info("");
+  }
+  logger.info("O que deseja fazer?");
+  if (hasEnv) {
+    logger.info(
+      `  1) Atualizar (recomendado) — sincroniza com a versão do pacote, preserva o ENV.md`
+    );
+  }
+  logger.info(`  2) Reinstalar — sobrescreve os arquivos do framework`);
+  logger.info(`  3) Cancelar`);
+  logger.info("");
+
+  const valid = hasEnv ? "1, 2 ou 3" : "2 ou 3";
+  for (;;) {
+    const answer = await askLine(`Escolha [${hasEnv ? "1" : "3"}]: `);
+    if (answer === null) {
+      logger.info("");
+      logger.info(
+        `${BLUE}ℹ️  Sem resposta: nada alterado. Use --upgrade (atualizar) ou --force (reinstalar).${NC}\n`
+      );
+      return "no-answer";
+    }
+    const choice = parseMenuChoice(answer, { hasEnv });
+    if (choice) return choice;
+    logger.info(`${RED}Opção inválida. Escolha ${valid}.${NC}`);
+  }
+}
+
 /**
  * Grava o Context7 (MCP obrigatório) no arquivo de MCP da IDE e mostra o que falta.
  * Só avisa: problema no arquivo de MCP não muda o código de saída (instalação e --upgrade).
@@ -73,6 +182,21 @@ export async function init(flags) {
     return;
   }
 
+  // Um leitor de linhas só para os dois menus (IDE e pasta já instalada), criado na primeira
+  // pergunta e fechado antes do sync ou do upgrade (que abre o seu, só com terminal).
+  let reader = null;
+  const askLine = (question) => {
+    if (!reader) {
+      const rl = createInterface({ input: process.stdin, terminal: false });
+      reader = { rl, next: lineReader(rl) };
+    }
+    return reader.next(question);
+  };
+  const closeReader = () => {
+    reader?.rl.close();
+    reader = null;
+  };
+
   let ide;
   if (flags.ide) {
     if (!isIDESupported(flags.ide)) {
@@ -100,14 +224,15 @@ export async function init(flags) {
     });
     logger.info("");
 
-    const rl = createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-
     let choice;
     while (true) {
-      choice = await ask(rl, `${BLUE}Digite o número da sua escolha (1-${IDES.length}): ${NC}`);
+      choice = await askLine(`${BLUE}Digite o número da sua escolha (1-${IDES.length}): ${NC}`);
+      if (choice === null) {
+        closeReader();
+        logger.info("");
+        logger.info(`${BLUE}ℹ️  Sem resposta: nada alterado. Use --ide {ide}.${NC}\n`);
+        return;
+      }
       const choiceNum = parseInt(choice, 10);
 
       if (choiceNum >= 1 && choiceNum <= IDES.length) {
@@ -128,40 +253,41 @@ export async function init(flags) {
         );
       }
     }
-
-    rl.close();
   }
 
   const ideDir = join(cwd, `.${getIDEFolder(ide)}`);
 
-  // Avisos de versão antes da pergunta de reinstalação: quem responde "s" (ou usa --force)
-  // já sabe se vai rebaixar os assets.
-  warnVersionMismatch(cwd);
+  // Avisos de versão antes do menu: quem escolhe reinstalar (ou usa --force) já sabe se vai
+  // rebaixar os assets. O resultado vai para o runUpgrade, que não repete o aviso (Q8).
+  const lockVersion = readLockVersion(cwd);
+  const versionCheck = warnVersionMismatch(cwd, lockVersion);
 
-  // Reinstall: --force ou confirmação "s" devem sobrescrever assets (cpSync force:true).
+  // Reinstalação: --force ou a opção 2 do menu sobrescrevem os assets (cpSync force:true).
   let forceSync = !!flags.force;
 
   if (existsSync(ideDir) && !forceSync) {
-    logger.info(`${YELLOW}⚠️  Framework já instalado em .${getIDEFolder(ide)}${NC}`);
-    logger.info("");
-
-    const rl = createInterface({
-      input: process.stdin,
-      output: process.stdout,
+    const choice = await askInstalledMenu({
+      folder: getIDEFolder(ide),
+      lockVersion,
+      packageVersion: versionCheck.running,
+      hasEnv: existsSync(join(ideDir, "ENV.md")),
+      askLine,
     });
-    const confirm = await ask(
-      rl,
-      `Deseja reinstalar? Isso irá sobrescrever a instalação existente. (s/N): `
-    );
-    rl.close();
-
-    if (confirm.toLowerCase() !== "s") {
+    closeReader();
+    if (choice === "upgrade") {
+      logger.info("");
+      process.exitCode = await runUpgrade(cwd, { ...flags, ide, versionCheck });
+      return;
+    }
+    if (choice === "no-answer") return;
+    if (choice === "cancel") {
       logger.info(`${BLUE}ℹ️  Instalação cancelada.${NC}\n`);
       return;
     }
     forceSync = true;
     logger.info("");
   }
+  closeReader();
 
   const ideConfig = getIDEConfig(ide);
   logger.info(`${BLUE}Configurando ambiente para ${ideConfig?.name}...${NC}`);
@@ -169,13 +295,15 @@ export async function init(flags) {
   const result = syncAssets(cwd, ide, {
     force: forceSync,
     workflowsFolder: getWorkflowsFolder(ide),
+    // Reinstalação não troca valor do ENV.md (RTK_ENABLED=false fica), como o upgrade (Q1).
+    keepEnvValues: forceSync,
   });
 
   for (const item of result.copied) {
     logger.info(`${BLUE}  ↳ ${item}${NC}`);
   }
   for (const item of result.skipped) {
-    logger.info(`${DIM}  ↳ ${item} (já existe)${NC}`);
+    logger.info(`${DIM}  ↳ ${item}${NC}`); // o motivo já vem no item (sync-engine)
   }
   for (const item of result.errors) {
     logger.error(`${RED}  ✗ ${item}${NC}`);
@@ -371,7 +499,9 @@ async function runUpgrade(cwd, flags) {
   const workspaceDir = resolved.root;
   const envPath = resolved.path;
   const previousVersion = readLockVersion(workspaceDir);
-  const { downgrade, running } = warnVersionMismatch(workspaceDir, previousVersion);
+  // Vindo do menu do `init`, o aviso já saiu antes da escolha (Q8): só reaproveita o resultado.
+  const { downgrade, running } =
+    flags.versionCheck ?? warnVersionMismatch(workspaceDir, previousVersion);
   if (downgrade && !flags.yes) {
     let go = false;
     if (process.stdin.isTTY) {
@@ -480,7 +610,11 @@ async function runUpgrade(cwd, flags) {
   // 4. Resumo (só nomes de chave e caminhos)
   const pkg = getPackageInfo();
   logger.info("");
-  logger.info(`${GREEN}✅ Upgrade concluído: ${previousVersion} → ${pkg.version}${NC}`);
+  logger.info(
+    previousVersion === pkg.version
+      ? `${GREEN}✅ Upgrade concluído: já na v${pkg.version} (arquivos ressincronizados)${NC}`
+      : `${GREEN}✅ Upgrade concluído: ${previousVersion} → ${pkg.version}${NC}`
+  );
   logger.info(`  • Arquivos do framework: ${sync.copied.length} item(ns) sincronizado(s)`);
   logger.info(
     `  • ENV.md: ${addedKeys.length ? `+ ${addedKeys.join(", ")}` : "nenhuma variável nova"}`
@@ -532,11 +666,12 @@ async function runUpgrade(cwd, flags) {
     const access = (futureEntries.get(`${key}_ACCESS`) || "").trim();
     return getVendor(futureEntries.get(key)) && (!access || /^\[.*\]$/.test(access));
   });
+  const pending = upgradePendencies({ pendingAxes, envPlan });
   logger.info("");
   logger.info(
-    pendingAxes.length
-      ? `${CYAN}➡️  Agora rode ${BOLD}/jarvis-init upgrade${NC}${CYAN} na IDE para confirmar o acesso de ${pendingAxes.join(" e ")} (e as variáveis).${NC}\n`
-      : `${CYAN}➡️  Agora rode ${BOLD}/jarvis-init upgrade${NC}${CYAN} na IDE.${NC}\n`
+    pending.length
+      ? `${CYAN}➡️  Agora rode ${BOLD}/jarvis-init upgrade${NC}${CYAN} na IDE: ${pending.join("; ")}.${NC}\n`
+      : `${GREEN}✓ Nada pendente na IDE.${NC}\n`
   );
   return sync.errors.length || moveErrors.length || staleErrors.length ? 1 : 0;
 }

package/bin/lib/cli/program.js

@@ -87,18 +87,18 @@ export function buildProgram() {
   const initCmd = cmd(program, "init")
     .description("Bootstrap do framework no workspace")
     .option("--ide <ide>", "IDE a configurar (pula o menu interativo)")
-    .option("--force", "Sobrescreve a instalação existente sem perguntar")
+    .option("--force", "Reinstala sem mostrar o menu: sobrescreve os arquivos do framework")
     .option(
       "--upgrade",
-      "Atualiza um projeto já configurado: arquivos do framework, variáveis novas do ENV e pastas de documentos"
+      "Atualiza sem mostrar o menu: arquivos do framework, variáveis novas do ENV e pastas de documentos"
     )
     .option(
       "--yes",
-      "Com --upgrade, move os documentos para as pastas novas e aceita rebaixar os assets sem perguntar"
+      "Com --upgrade (ou a opção Atualizar do menu), move os documentos para as pastas novas e aceita rebaixar os assets sem perguntar"
     )
     .option(
       "--remove-stale",
-      "Com --upgrade, remove sem perguntar os skills instalados que saíram do framework (só os listados)"
+      "Com --upgrade (ou a opção Atualizar do menu), remove sem perguntar os skills instalados que saíram do framework (só os listados)"
     );
   withLogOptions(initCmd).action((options) => init(toLegacyFlags(options)));
 

package/bin/lib/core/sync-engine.js

@@ -80,7 +80,7 @@ export function syncAssets(targetDir, ide, opts = {}) {
     const dest = join(ideDir, destDirName);
 
     if (!existsSync(src)) {
-      result.skipped.push(`${dir}/ (not found in framework)`);
+      result.skipped.push(`${dir}/ (não existe no framework)`);
       continue;
     }
 
@@ -102,7 +102,7 @@ export function syncAssets(targetDir, ide, opts = {}) {
     if (!existsSync(src)) continue;
 
     if (existsSync(dest) && !opts.force) {
-      result.skipped.push(`${file} (already exists)`);
+      result.skipped.push(`${file} (já existe)`);
       continue;
     }
 
@@ -228,7 +228,11 @@ function reconcileRtk(ideDir, targetDir, ide, { keepEnvValues = false } = {}) {
         return "(rtk) detectado — RTK_ENABLED=true no ENV.md";
       }
       if (!env.includes("RTK_ENABLED")) {
-        env = env.trimEnd() + "\n\n# --- RTK — Token Killer ---\nRTK_ENABLED=true\n";
+        // Moldura do ENV-template (#189): o /jarvis-init não aponta o bloco como separador antigo.
+        const bar =
+          "# =============================================================================";
+        env =
+          env.trimEnd() + `\n\n${bar}\n# RTK — Token Killer (opcional)\n${bar}\nRTK_ENABLED=true\n`;
         writeFileSync(envPath, env, "utf-8");
         return "(rtk) detectado — RTK_ENABLED=true adicionado ao ENV.md";
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jarvis-ai-framework",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "description": "Jarvis framework",
   "type": "module",
   "bin": {
@@ -11,7 +11,7 @@
     "prepublishOnly": "echo 'Publishing jarvis-framework...'",
     "publish:gitlab": "npm publish",
     "test:comandos": "node test/comandos-docs.test.js",
-    "test:filtro": "node --test test/profile-filter.test.js test/token-report.test.js test/flow-map.test.js test/env-loader.test.js test/sync-engine.test.js test/vcs-api.test.js test/fetch-file.test.js test/publish-file.test.js test/docs-storage.test.js test/env-upgrade.test.js test/docs-migrate.test.js test/init-upgrade.test.js test/workspace-mode.test.js test/stale-skills.test.js test/session-scan.test.js test/framework-refs.test.js test/validate-frontmatter.test.js test/mcp-config.test.js test/integrations-catalog.test.js test/cli-runner.test.js test/tasks-comment.test.js test/version.test.js test/gate-checklist-rodadas.test.js test/publish-comments-rules.test.js",
+    "test:filtro": "node --test test/profile-filter.test.js test/token-report.test.js test/flow-map.test.js test/env-loader.test.js test/sync-engine.test.js test/vcs-api.test.js test/fetch-file.test.js test/publish-file.test.js test/docs-storage.test.js test/env-upgrade.test.js test/docs-migrate.test.js test/init-upgrade.test.js test/workspace-mode.test.js test/stale-skills.test.js test/session-scan.test.js test/framework-refs.test.js test/validate-frontmatter.test.js test/mcp-config.test.js test/integrations-catalog.test.js test/cli-runner.test.js test/tasks-comment.test.js test/version.test.js test/gate-checklist-rodadas.test.js test/publish-comments-rules.test.js test/pre-pr-criterio.test.js test/nomes-soltos.test.js",
     "lint": "eslint bin/ test/",
     "lint:fix": "eslint bin/ test/ --fix",
     "format": "prettier --write bin/ test/",

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

@@ -211,6 +211,7 @@ Para cada tarefa, incluir:
 
 ### Fase 5: Validação
 
+0. **Executar** o Checklist de Conclusão (abaixo) item a item contra o `plan.md` e corrigir o plano antes de apresentar (passe crítico, Fase 4 do workflow)
 1. **Apresentar** o plano ao humano
 2. **Discutir** ajustes necessários
 3. **Atualizar** `architecture.md` se houver mudanças arquiteturais
@@ -300,6 +301,7 @@ Antes de considerar o plano completo:
 - [ ] Dependências estão claras (sequencial/paralelo)
 - [ ] Status iniciais definidos (todos ⏳)
 - [ ] Conteúdo em português (pt-BR)
+- [ ] Passe crítico executado (este checklist conferido item a item) e "Ajustes antes da aprovação" atualizado no cabeçalho a cada "Ajustar o plano"
 - [ ] Validado com o humano
 - [ ] `plan.md` criado em `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/`
 

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

@@ -75,9 +75,11 @@ Avaliar **apenas** as mudanças da branch atual em relação à branch base (`Br
 git diff {BRANCH_BASE}...HEAD
 ```
 
+Da rodada 2 em diante, cada gate roda só se o diff desde o `Commit:` da rodada anterior tocar o que ele lê (seção "Rodada incremental" do `eng.pre-pr.md`). O gate que roda continua revisando a branch inteira.
+
 ### Evidências Obrigatórias
 
-Cada lacuna cita onde está (`arquivo:linha`) ou o comando que a revelou e o resultado.
+Cada lacuna cita onde está (`arquivo:linha` com o trecho) ou o comando que a revelou e o resultado, **e o que a derrubaria** (coluna Refutação). Antes de gravar, o passe crítico (seção "Passe crítico" do `eng.pre-pr.md`) remove a lacuna cuja refutação se sustenta e rebaixa a que pesa menos do que a severidade dada.
 
 ---
 
@@ -86,9 +88,12 @@ Cada lacuna cita onde está (`arquivo:linha`) ou o comando que a revelou e o res
 O workflow **deve sempre** terminar com:
 
 1. **`gate-checklist.md`** em `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/`:
-   - semáforo (🟢 / 🟡 / 🔴), resumo, lacunas por área (o quê, onde, por que importa, sugestão, severidade, **Decisão**), evidências e PR Brief.
+   - semáforo (🟢 / 🟡 / 🔴), resumo (com a linha `Critério de parada:`), lacunas por área (o quê, com o "(item N)" do gate que a achou no fim, onde, por que importa, refutação, sugestão, severidade, **Decisão**), evidências e PR Brief (com as rodadas por severidade, a rodada em que o critério de parada agiu, os ajustes do `architecture.md` e do `plan.md` antes da aprovação e as lições desta tarefa; guardar lições entre tarefas não é deste comando, é da #169).
    - `Rodada` e `Commit` no cabeçalho, as rodadas anteriores e, da rodada 2 em diante, a resolução das lacunas da rodada anterior.
+   - Da rodada 2 em diante, as áreas cujos gates não rodaram na rodada incremental, marcadas como "Não reavaliada nesta rodada".
    - É sempre a rodada mais recente: ao rodar de novo na mesma sessão, o relatório existente é preservado como `gate-checklist-rodada-{N}.md` (seção "Rodadas" do `eng.pre-pr.md`). **Nunca** sobrescrever nem apagar uma rodada; renomear imediatamente antes de gravar.
-2. **Decisões do usuário** gravadas na coluna Decisão (🔧 Corrigir / 👍 Aceitar + motivo; vazia se o usuário escolheu "Só gerar o relatório", exceto as decisões herdadas da rodada anterior).
+2. **Decisões do usuário** gravadas na coluna Decisão (🔧 Corrigir / 👍 Aceitar + motivo; vazia se o usuário escolheu "Só gerar o relatório", exceto as decisões herdadas da rodada anterior). Na variante B do fechamento, as ⚪ aceitas levam `👍 Aceitar: aceito no fechamento da rodada {N}` e as 🟡 aceitas em bloco (só com o teto atingido) levam `👍 Aceitar: teto de rodadas atingido na rodada {N}`, e as decididas uma a uma levam o motivo dado pela pessoa; decisão herdada nunca é trocada.
+   - **Critério de parada** (seção "Fechamento" do `eng.pre-pr.md`): teto de rodadas pela urgência do `context.md` (`alta` 3 · `normal` 5 · `baixa` 8) ou rodada sem lacuna 🔴 ou 🟡 nova (com os itens 2 e 3 tendo rodado). Sem 🔴 pendente nem 🟡 herdada com `🔧 Corrigir`, e com só ⚪ sem decisão (ou também 🟡, com o critério de parada atingido), o fechamento usa a variante B. Na variante B, "Aceitar as ⚪ e seguir para o PR" é a primeira opção (a recomendada) e "Só gerar o relatório" mantém o fluxo de hoje. Só o teto aceita 🟡 em bloco; com o gatilho "sem lacuna nova", as 🟡 são decididas uma a uma. O critério nunca pula a revisão nem a gravação. Fora desses casos (por exemplo, com 🔴 pendente), o ciclo segue na variante A. Sempre que o teto for atingido e houver pendência, o fechamento avisa.
+   - **Pendentes não reavaliadas** (rodada incremental): a lacuna pendente da rodada anterior cujo gate de origem (o "(item N)" da coluna Lacuna) não rodou é copiada para a rodada nova, com a decisão herdada.
 3. **Pergunta** (`AskUserQuestion`) sobre registrar o resultado como comentário no card (`/eng-global-task-comment`): Não, manter só na sessão (como hoje) / Sim, só o resumo / Sim, o relatório completo. Nunca publicar sem a resposta. Freelance: não pergunta, só na sessão.
 4. **Aguardar permissão explícita** do usuário para prosseguir para `/eng.pr`.