jarvis-ai-framework 7.0.0 → 8.2.0

package/bin/commands/init.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
-import { join, dirname, basename } from "node:path";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, dirname, basename, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 import { syncAssets } from "../lib/core/sync-engine.js";
 import { discoverAll } from "../lib/core/scanner.js";
@@ -16,6 +16,7 @@ import { getPackageInfo, getFrameworkRoot } from "../lib/utils/paths.js";
 import { logger, configureFromFlags } from "../lib/utils/logger.js";
 import { resolveEnvPath } from "../lib/env-loader.js";
 import { LOCK_FILE } from "../lib/config/constants.js";
+import { compareVersions, localInstall } from "../lib/utils/version.js";
 import {
   findStaleSkills,
   registeredSpecializations,
@@ -38,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).
@@ -72,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)) {
@@ -99,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) {
@@ -127,36 +253,41 @@ export async function init(flags) {
         );
       }
     }
-
-    rl.close();
   }
 
   const ideDir = join(cwd, `.${getIDEFolder(ide)}`);
 
-  // Reinstall: --force ou confirmação "s" devem sobrescrever assets (cpSync force:true).
+  // 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);
+
+  // 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}`);
@@ -164,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}`);
@@ -257,6 +390,53 @@ function ideFromEnvPath(envPath) {
   return getIDEValues().find((v) => `.${getIDEFolder(v)}` === folder);
 }
 
+/**
+ * Avisos de versão antes do sync. O Jarvis é instalado só global:
+ * - cópia local no projeto (`node_modules` ou dependência no `package.json`) é ignorada;
+ *   se é ela que está rodando (`npx jarvis`, `./node_modules/.bin/jarvis`), o aviso diz isso;
+ * - lock do projeto mais novo que o Jarvis em uso: o sync rebaixaria os assets.
+ * Recebe o lock lido antes do `syncAssets`, que o reescreve.
+ * @param {string} workspaceDir
+ * @param {string} [lock] - versão do `jarvis-lock.json` do projeto
+ * @returns {{ downgrade: boolean, running: string }} `downgrade` = lock mais novo que o Jarvis em uso
+ */
+export function warnVersionMismatch(workspaceDir, lock = readLockVersion(workspaceDir)) {
+  const running = getPackageInfo().version;
+  // Caminhos reais dos dois lados: o Node já resolve o link do script (`import.meta.url`),
+  // então uma cópia por `npm link` em node_modules só bate com o realpath.
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return resolve(p);
+    }
+  };
+  const root = real(getFrameworkRoot());
+  const localDir = join(workspaceDir, "node_modules", "jarvis-ai-framework");
+  const runningLocal =
+    (root + sep).startsWith(real(join(workspaceDir, "node_modules")) + sep) ||
+    (existsSync(localDir) && root === real(localDir));
+  const local = localInstall(workspaceDir);
+  if (runningLocal) {
+    logger.info(
+      `${BLUE}ℹ️  O Jarvis em uso (${running}) é o mesmo de node_modules (cópia local do projeto). O Jarvis é instalado global: npm install -g jarvis-ai-framework, rode \`jarvis\` (sem npx) e remova a cópia local.${NC}`
+    );
+  } else if (local) {
+    logger.info(
+      `${BLUE}ℹ️  O Jarvis é instalado global (npm install -g jarvis-ai-framework). A cópia local deste projeto (${local.version} em ${local.source}) é ignorada: pode removê-la.${NC}`
+    );
+  }
+  const downgrade = compareVersions(lock, running) === 1;
+  if (downgrade) {
+    const who = runningLocal ? "o Jarvis em uso (cópia local)" : "o seu jarvis global";
+    logger.info(
+      `${YELLOW}⚠️  Os assets deste projeto são da ${lock}, mas ${who} é a ${running}. Atualize o global: npm install -g jarvis-ai-framework${NC}`
+    );
+  }
+  if (runningLocal || local || downgrade) logger.info("");
+  return { downgrade, running };
+}
+
 function readLockVersion(workspaceDir) {
   try {
     return (
@@ -319,6 +499,29 @@ async function runUpgrade(cwd, flags) {
   const workspaceDir = resolved.root;
   const envPath = resolved.path;
   const previousVersion = readLockVersion(workspaceDir);
+  // 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) {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await ask(
+        rl,
+        `Seguir e rebaixar os assets de ${previousVersion} para ${running}? (s/N): `
+      );
+      rl.close();
+      go = answer.trim().toLowerCase() === "s";
+    } else {
+      logger.info(`${DIM}  Sem terminal interativo e sem --yes: nada será rebaixado.${NC}`);
+    }
+    if (!go) {
+      logger.info(
+        `${YELLOW}Upgrade interrompido: atualize o global (npm install -g jarvis-ai-framework) e rode de novo.${NC}\n`
+      );
+      return 1;
+    }
+  }
 
   // 1. Arquivos do framework (o ENV.md não está entre os sincronizados)
   logger.info(`${BLUE}⬆️  Upgrade do Jarvis em .${getIDEFolder(ide)}/${NC}\n`);
@@ -407,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"}`
@@ -459,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

@@ -22,7 +22,6 @@ import { info } from "../../commands/info.js";
 import { whoami } from "../../commands/whoami.js";
 import { docsSync } from "../../commands/docs-sync.js";
 import { docsPublish } from "../../commands/docs-publish.js";
-import { qaSignoff } from "../../commands/qa-signoff.js";
 import { installRtk } from "../../commands/install-rtk.js";
 import { tokens } from "../../commands/tokens.js";
 import { map } from "../../commands/map.js";
@@ -88,15 +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 (ou a opção Atualizar do menu), move os documentos para as pastas novas e aceita rebaixar os assets sem perguntar"
     )
-    .option("--yes", "Com --upgrade, move os documentos para as pastas novas 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)));
 
@@ -162,12 +164,6 @@ export function buildProgram() {
   );
   withLogOptions(installRtkCmd).action((options) => installRtk(toLegacyFlags(options)));
 
-  const qaSignoffCmd = cmd(program, "qa-signoff")
-    .description("Verificar sign-off QA válido para a branch atual (usado pelo CI)")
-    .option("--branch <branch>", "Branch a verificar (padrão: lido do git)")
-    .option("--max-age <horas>", "Validade máxima em horas (padrão: 24)");
-  withEnvOptions(qaSignoffCmd).action((options) => qaSignoff(toLegacyFlags(options)));
-
   cmd(program, "tokens")
     .description("Estimar o que carrega no início da sessão")
     .option("--hub <hub>")

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";
       }
@@ -575,7 +579,7 @@ function writeLockFile(targetDir, ideDir, ide, frameworkRoot) {
 
   const lockContent = JSON.stringify(lock, null, 2) + "\n";
 
-  // Write lock file to project root (for postinstall.js)
+  // Write lock file to project root (lido pelo jarvis init --upgrade e pelo Passo 0 do /jarvis-init)
   writeFileSync(join(targetDir, LOCK_FILE), lockContent);
 
   // Also write lock file to IDE folder

package/bin/lib/utils/frontmatter.js

@@ -1,6 +1,6 @@
 /**
  * @fileoverview Leitura de frontmatter YAML (`---\n...\n---`) compartilhada
- * entre scanner.js, validate-frontmatter.js, qa-signoff.js e sync-engine.js —
+ * entre scanner.js, validate-frontmatter.js e sync-engine.js —
  * cada um tinha sua própria cópia da mesma regex de bloco.
  * @module utils/frontmatter
  */

package/bin/lib/utils/paths.js

@@ -18,7 +18,8 @@ export function getFrameworkRoot() {
   }
 
   throw new Error(
-    "Could not locate framework assets.\n" + "Run: npm install jarvis-framework --save-dev"
+    "Não foi possível localizar os assets do framework.\n" +
+      "Instale o Jarvis global: npm install -g jarvis-ai-framework"
   );
 }
 

package/bin/lib/utils/version.js

@@ -0,0 +1,65 @@
+import { lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PACKAGE = "jarvis-ai-framework";
+
+/**
+ * Compara duas versões `x.y.z` (aceita `v` na frente e ignora o sufixo, como `-beta.1`).
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1 | 0 | 1 | null} `null` se uma das duas não for uma versão legível
+ */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const m = String(v ?? "")
+      .trim()
+      .match(/^v?(\d+)\.(\d+)\.(\d+)/);
+    return m ? m.slice(1).map(Number) : null;
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
+  }
+  return 0;
+}
+
+// lstat não segue o link: um link simbólico quebrado também conta como presente.
+function exists(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Cópia local do Jarvis no projeto, que é ignorada (o Jarvis é instalado só global).
+ * @param {string} workspaceDir
+ * @returns {{ version: string, source: string } | null} a versão instalada em `node_modules`
+ *   ("desconhecida" se ilegível), ou a faixa declarada no `package.json`; `null` sem nenhuma das duas
+ */
+export function localInstall(workspaceDir) {
+  const installed = join(workspaceDir, "node_modules", PACKAGE, "package.json");
+  if (exists(join(workspaceDir, "node_modules", PACKAGE))) {
+    // Pasta (ou link, mesmo quebrado) presente, sem package.json legível: ainda é uma cópia local.
+    const version = readJson(installed)?.version || "desconhecida";
+    return { version, source: `node_modules/${PACKAGE}` };
+  }
+  const pkg = readJson(join(workspaceDir, "package.json"));
+  for (const field of ["dependencies", "devDependencies"]) {
+    const range = pkg?.[field]?.[PACKAGE];
+    if (range) return { version: range, source: `package.json (${field})` };
+  }
+  return null;
+}

package/bin/postinstall.js

@@ -1,41 +1,17 @@
-import { existsSync, readFileSync } from "node:fs";
 import { execSync } from "node:child_process";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const cwd = process.env.INIT_CWD || process.cwd();
-const lockPath = join(cwd, "jarvis-lock.json");
-
-// ── Sincronizar assets para projetos com jarvis-lock.json ───────────────────
-if (existsSync(lockPath)) {
-  try {
-    const lock = JSON.parse(readFileSync(lockPath, "utf-8"));
-    const { syncAssets } = await import("./lib/core/sync-engine.js");
-    const { getWorkflowsFolder } = await import("./lib/config/ide-config.js");
-    const { logger } = await import("./lib/utils/logger.js");
-    logger.info(`\n  jarvis-framework — syncing to .${lock.ide}/\n`);
-    const result = syncAssets(cwd, lock.ide, {
-      force: true,
-      workflowsFolder: getWorkflowsFolder(lock.ide),
-    });
-    logger.info(`  ${result.copied.length} items synced.\n`);
-  } catch {}
-} else {
-  const { logger } = await import("./lib/utils/logger.js");
-  logger.info(`
-  jarvis-framework installed.
-  Run: npx jarvis init --ide windsurf
+// O Jarvis é instalado só global (npm install -g); o postinstall só dá as dicas.
+// A atualização dos assets de um projeto tem um caminho só: jarvis init --upgrade, dentro dele.
+const { logger } = await import("./lib/utils/logger.js");
+logger.info(`
+  jarvis-ai-framework instalado.
+  No projeto: jarvis init --ide {ide}   (ou jarvis init --upgrade para atualizar os assets)
 `);
-}
 
 // ── Sugestão RTK (sempre, se rtk não estiver instalado) ─────────────────────
 try {
   execSync("rtk gain --help 2>/dev/null", { stdio: "pipe" });
 } catch {
-  const { logger } = await import("./lib/utils/logger.js");
   logger.info(`  💡 Dica: instale o RTK para economizar 60-90% dos tokens de shell.`);
-  logger.info(`     npx jarvis install-rtk\n`);
+  logger.info(`     jarvis install-rtk\n`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jarvis-ai-framework",
-  "version": "7.0.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: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/AGENTS.md

@@ -169,7 +169,7 @@ Links para documentacao relacionada.
 |------|----------|-----------|
 | Planejamento | `eng.start`, `eng.plan` | Somente analise, SEM codigo |
 | Implementacao | `eng.work` | Codigo e testes, commit por fase, SEM push nem PR |
-| Entrega | `eng.pr` | Branch, commit e PR |
+| Entrega | `eng.pr` | Push e PR, depois da pergunta (regra de ouro) |
 
 ### Seguranca
 

package/rules/engineering/data/data-rules.md

@@ -67,7 +67,7 @@ expect_table_row_count_to_be_between(min_value=last_run_count * 0.5)
 ### Falha de qualidade
 
 - **Bronze → Silver**: falha bloqueia a promoção. Dados permanecem em bronze.
-- **Silver → Gold**: falha bloqueia publicação. Alerta no Slack canal do time de Data.
+- **Silver → Gold**: falha bloqueia publicação. Alerta automático do pipeline no Slack canal do time de Data (runtime; um aviso enviado pelo Jarvis só sai depois da pergunta, regra de ouro).
 - Nunca silenciar falhas — registrar no log com contexto da execução.
 
 ---
@@ -116,7 +116,7 @@ logger.info({
 
 - **AWS Glue**: logs automáticos no CloudWatch (`/aws-glue/jobs/output`)
 - **Airflow**: logs nas tasks do DAG + CloudWatch quando em produção
-- **Erros críticos**: alertar no canal Slack do time de Data (`#data-alerts` ou equivalente)
+- **Erros críticos**: alerta automático do pipeline no canal Slack do time de Data (`#data-alerts` ou equivalente; runtime. Um aviso enviado pelo Jarvis só sai depois da pergunta, regra de ouro)
 
 ### Retenção
 

package/rules/engineering/eng-rules.md

@@ -65,7 +65,7 @@ env_file: "@/ENV.md"
   - No modo workspace a raiz (a pasta que contém `$IDE/`) **não é um repositório** e guarda itens fora do git (`.claude/`, `.jarvis/`, `.vscode/`, `node_modules/`). `grep`, `ls` e `Glob` na raiz leem tudo isso como se fosse código do projeto e confundem a análise.
   - **Código do projeto** = só as subpastas com `.git/` (ou as de `WORKSPACE_REPOS`, quando preenchido). Busque e leia código **dentro delas**.
   - **Ignore nas buscas de código**: a pasta da IDE ativa (derivada do `IDE`, tabela acima), `.jarvis/`, `.vscode/`, `node_modules/` e o `CDD-MIND-MAP.md`. Leia esses itens **só quando o workflow mandar** (ENV.md, rules, skills, templates, sessão).
-  - **`docs/jarvis/` não é ignorada**: guarda os documentos de trabalho gerados (PRD, FRD, ARD, RFC, SPEC, discoveries, Central docs), fora do versionamento. Leia-a sob demanda, como documento de trabalho, e não como código.
+  - **`docs/jarvis/` não é ignorada**: guarda os documentos de trabalho gerados (PRD, FRD, ARD, RFC, SPEC, discoveries) e, com storage `filesystem`, a cópia local do Central docs (`central-docs/`, no local padrão; o registro do implementado), fora do versionamento. Leia-a sob demanda, como documento de trabalho ou registro, e não como código.
   - **Pastas de outras IDEs** nunca são lidas (vale o "Isolamento de IDE" acima).
   - Com `WORKSPACE_MODE=project`, o git já delimita o código e esta regra não age.
 

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

@@ -105,7 +105,7 @@ O agente DEVE incluir no checklist de pre-PR as seguintes verificacoes de segura
 - [ ] **Outputs**: erros nao vazam detalhes internos
 
 Se o PR toca em areas sensiveis (auth, sessions, RBAC, CORS, CSP, permissoes), o agente DEVE:
-1. Adicionar label `security` ao PR
+1. Registrar no PR Brief do `gate-checklist.md` que o PR leva o label `security` e orientar a pessoa a adiciona-lo ao PR (o Jarvis nao altera o PR no vendor sem perguntar, regra de ouro; o `jarvis vcs create-merge` nao poe label)
 2. Seguir o gate de seguranca inline do `eng.pre-pr` (sanitizacao, auth guards, headers, secrets scan, `npm audit`) antes do merge
 
 ---