jarvis-ai-framework 7.0.0 → 8.1.0

package/AGENTS.md

@@ -255,7 +255,7 @@ Cada pasta pode ter seu proprio AGENTS.md com instrucoes especificas:
 /eng.plan "feature"      # Plano de execucao faseado (somente planejamento)
 /eng.work "feature"      # Implementacao e testes (commit por fase, sem push/PR)
 /eng.pre-pr              # Validacao pre-PR
-/eng.pr                  # Cria branch, commit e PR
+/eng.pr                  # Push e PR, depois da pergunta (regra de ouro)
 ```
 
 ### Documentacao
@@ -285,7 +285,7 @@ Tabela completa de mapeamento comando/trigger → skill: ver `$IDE/skills/AGENTS
 |------|---------|-----------|
 | 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) |
 
 ---
 

package/README.md

@@ -14,18 +14,13 @@
 
 ### 1. Instale
 
-Global (comando `jarvis` no PATH):
+O Jarvis é instalado **só global** (comando `jarvis` no PATH):
 
 ```bash
 npm install -g jarvis-ai-framework
 ```
 
-**Só neste workspace** (não sobe no PATH):
-
-```bash
-cd workspace-squad/
-npm install jarvis-ai-framework --save-dev
-```
+Não instale o pacote dentro do projeto: o `jarvis init` roda **dentro do projeto** e copia os assets do Jarvis global para a pasta da IDE. Se ele achar uma cópia local (`node_modules` ou dependência no `package.json`), avisa que ela é ignorada.
 
 Confira **onde** o binário ficou no PATH (útil se houver mais de uma instalação):
 
@@ -42,8 +37,6 @@ jarvis --version
 jarvis init --ide cursor
 ```
 
-Se instalou só com `--save-dev`, use `npx jarvis init --ide cursor`.
-
 IDEs: `windsurf` · `claude` · `cursor` · `codex` · `opencode` · `gemini` · `kiro`
 
 ### 3. No chat da IDE
@@ -76,13 +69,6 @@ Global (comando `jarvis` no PATH):
 npm install -g /caminho/para/jarvis
 ```
 
-**Só neste workspace** (não sobe no PATH):
-
-```bash
-cd workspace-squad/
-npm install /caminho/para/jarvis --save-dev
-```
-
 **`npm link`** (útil se você altera o clone e quer refletir na hora):
 
 ```bash
@@ -90,12 +76,7 @@ cd /caminho/para/jarvis
 npm link
 ```
 
-Isso já registra o comando `jarvis` no global. Opcional, para o workspace resolver o pacote:
-
-```bash
-cd workspace-squad/
-npm link jarvis-ai-framework
-```
+Isso já registra o comando `jarvis` no global. Não rode `npm link jarvis-ai-framework` dentro do workspace: isso cria uma cópia local em `node_modules`, que o `jarvis init` ignora (e avisa).
 
 Confira **onde** o binário ficou no PATH (útil se houver mais de uma instalação):
 
@@ -137,12 +118,6 @@ git pull
 npm install -g /caminho/para/jarvis
 ```
 
-**Só no workspace (`--save-dev`):**
-```bash
-cd workspace-squad/
-npm install /caminho/para/jarvis --save-dev
-```
-
 **Com `npm link`:** o `git pull` no clone já basta — o link aponta para a pasta.
 
 Antes de seguir, confira se o `jarvis` do PATH é o que você acabou de atualizar:
@@ -164,7 +139,7 @@ jarvis init --ide cursor
 
 Isso copia de novo `agents/`, `skills/`, `workflows/`, `rules/`, `templates/` para `.$IDE/` e atualiza o `jarvis-lock.json`.
 
-Se o workspace usa `--save-dev` e já tem `jarvis-lock.json`, o `npm install` do passo 2 também dispara o **postinstall** e sincroniza sozinho para a IDE do lock.
+Esse é o único caminho de atualização dos assets: o `npm install -g` não sincroniza nenhum projeto sozinho. Quando os assets do projeto estão atrás do Jarvis global, o `/jarvis-init` avisa no início e oferece o `jarvis init --upgrade`.
 
 ### 4. ENV.md (só se houver variáveis novas)
 
@@ -183,8 +158,8 @@ Escolha **Upgrade (C)** — adiciona chaves novas do template sem apagar os valo
 | Passo | O que muda |
 |-------|------------|
 | `git pull` | Código do framework no clone |
-| `npm install -g` / `--save-dev` | Binário `jarvis` + pacote que o `init` lê |
-| `jarvis init` (ou postinstall com lock) | Arquivos em `.$IDE/` (skills, agents, workflows…) e o Context7 no arquivo de MCP da IDE (ex.: `.mcp.json` no Claude Code; só acrescenta, sem apagar outros servidores) |
+| `npm install -g` | Binário `jarvis` + pacote que o `init` lê |
+| `jarvis init` | Arquivos em `.$IDE/` (skills, agents, workflows…) e o Context7 no arquivo de MCP da IDE (ex.: `.mcp.json` no Claude Code; só acrescenta, sem apagar outros servidores) |
 | `/jarvis-init` Upgrade | Só `$IDE/ENV.md` (variáveis faltantes) e, se você aceitar o passo opcional "adicionar as stacks", as listas de especializações |
 
 `ENV.md`, `.jarvis/sessions/` e o `.gitignore` do workspace **não** são sobrescritos pelo sync de assets. O `.gitignore` só é criado ou alterado quando a raiz tem `.git`; sem `.git` (como no modo workspace) a raiz não é versionada e o init não o toca.
@@ -212,7 +187,7 @@ O `/jarvis-init` pergunta o `ARTIFACT_STYLE` (variável do `ENV.md`):
 | Valor | O que acontece |
 |---|---|
 | `ai-generated` (padrão) | Como sempre: metadados, links de rastreabilidade e padrões da ferramenta |
-| `human-generated` | Nada do que o Jarvis publica (commit, PR/MR, comentário no card, issue) leva marca de IA ou da IDE: o `/eng.pr` confere e limpa antes do push. Todo documento gerado pergunta, no fim, se você quer a versão humanizada, gravada ao lado como `{nome}.public.md` para repassar a clientes ou stakeholders |
+| `human-generated` | Nada do que o Jarvis publica (commit, PR/MR, comentário no card, issue; sempre depois da pergunta) leva marca de IA ou da IDE: o `/eng.pr` confere e limpa antes do push. Todo documento gerado pergunta, no fim, se você quer a versão humanizada, gravada ao lado como `{nome}.public.md` para repassar a clientes ou stakeholders |
 
 Com `human-generated`, o `/jarvis-init` copia a rule `rules/artifact-style-rules.md` (eixo `ARTIFACT_STYLE` do `Applies to`); com `ai-generated`, ela nem existe na sessão. Trocou o valor à mão? Rode `/jarvis-init upgrade`.
 
@@ -253,6 +228,6 @@ Precisa de ajuda?
 - **Engenharia (um guia por comando `eng.*`)** — [`docs/engenharia/`](docs/engenharia/README.md)
 - **Indice de docs/** — [`docs/README.md`](docs/README.md)
 - **Instrucoes para agentes / mapa de skills** — `AGENTS.md`
-- **Issues/Feedback** — skill `jarvis-report-issue` (sem a CLI do host (`gh`), sem login ou sem rede, o issue fica em `.jarvis/issues/issue-{desc}.md` para abrir à mão)
+- **Issues/Feedback** — skill `jarvis-report-issue` (pergunta antes de abrir; sem a CLI do host (`gh`), sem login, sem rede ou com o seu Não, a issue fica em `.jarvis/issues/issue-{desc}.md` para abrir à mão)
 - **Duvidas sobre comandos** — Pergunte diretamente ao agent:
   `"Como funciona /eng.start?"` | `"Qual a diferenca entre /eng.work e /pr?"` | `"O que e CDD?"`

package/agents/engineering/data/eng.data-engineer.agent.md

@@ -66,7 +66,7 @@ Ativado quando há suspeita de dado incorreto, queda de volume ou falha de pipel
 - Identificar causa raiz: fonte, transformação ou carga
 - Verificar logs de execução e checks de qualidade
 - Propor correção e plano de reprocessamento idempotente
-- Alertar squads afetadas com contexto claro
+- Alertar squads afetadas com contexto claro (mostrando a mensagem e perguntando antes de enviar, regra de ouro)
 
 **Skill integrada**: `$IDE/skills/eng-data/SKILL.md` + `DATA_SPECIALIZATIONS`
 
@@ -126,7 +126,7 @@ CONTEXT_PROFILE:
 
 | Sinal | Urgência | Comportamento |
 |-------|----------|---------------|
-| `dado errado em produção`, `dashboard parado`, `pipeline falhou` | **CRÍTICA** | Fast track: diagnóstico imediato, isolar causa, comunicar squads afetadas |
+| `dado errado em produção`, `dashboard parado`, `pipeline falhou` | **CRÍTICA** | Fast track: diagnóstico imediato, isolar causa, comunicar squads afetadas (texto pronto; o envio só depois da pergunta, regra de ouro) |
 | `atraso`, `dado desatualizado`, `queda de volume` | **ALTA** | Investigação ágil, reprocessar com idempotência |
 | `nova feature`, `novo pipeline`, `contrato de dados` | **NORMAL** | Fluxo completo: documentar antes, implementar, validar |
 | `melhoria`, `refactoring de query`, `otimização` | **BAIXA** | Análise cuidadosa de impacto antes de qualquer mudança |
@@ -226,7 +226,7 @@ Para detecção automática de contexto de tarefas:
 ### 3. Qualidade e Monitoramento
 
 - Bloquear promoção de camada quando falha de qualidade ocorre
-- Alertar no canal do time de Data quando falha afeta `gold`
+- Alertar no canal do time de Data quando falha afeta `gold` (depois da pergunta, regra de ouro; o alerta automático de pipeline é do runtime)
 - Manter tabela `gold.pipeline_audit` com metadados de execução
 
 ### 4. Política de Dados Sensíveis

package/agents/engineering/eng.docs-consolidator.agent.md

@@ -15,7 +15,7 @@ tools: Read, Glob, Grep, Bash, Write, Edit
 
 Você transforma o que foi **implementado** num registro que dure. Duas pessoas vão ler o que você escreve:
 - **humanos:** outro squad, alguém novo no time, a própria pessoa daqui a seis meses;
-- **IAs:** o `/warm-up`, o `/eng.start` e os `/prod.spec.*` consultam o Central docs como verdade sobre o sistema.
+- **IAs:** o `/warm-up`, o `/eng.start` e os `/prod.spec.*` consultam o Central docs como verdade sobre o que está implementado.
 
 Por isso o texto tem de ser **completo, autossuficiente e sem ambiguidade**.
 
@@ -46,7 +46,7 @@ Por isso o texto tem de ser **completo, autossuficiente e sem ambiguidade**.
 4. `git log {base}..HEAD --format='%h|%an|%ad|%s' --date=short` e `git diff --stat {base}...HEAD`.
 5. O código alterado, só leitura, para confirmar o comportamento real.
 6. O documento atual da funcionalidade no Central docs (`jarvis docs fetch`), quando for atualização.
-7. O `gate-checklist.md` e o `pull-request.md` da sessão, se existirem.
+7. O `gate-checklist.md` (a rodada mais recente; as anteriores, `gate-checklist-rodada-{N}.md`, são histórico) e o `pull-request.md` da sessão, se existirem.
 
 ## O que você produz
 

package/agents/engineering/qa/eng.qa.quality-champion-task-agent.md

@@ -39,7 +39,7 @@ Você opera estritamente dentro do **contexto de tarefas Jira e especificações
    - Casos extremos não cobertos
    - Riscos potenciais, ambiguidades ou complexidade oculta
 
-5. Comentar melhorias diretamente no Jira:
+5. Comentar melhorias no Jira pelo `/eng-global-task-comment`, que mostra o texto e pergunta antes de enviar (regra de ouro, `eng.integrations-rules.md`):
    - Sugerir redação mais clara
    - Propor critérios de aceitação faltantes
    - Recomendar cenários de teste adicionais
@@ -54,7 +54,7 @@ Você opera estritamente dentro do **contexto de tarefas Jira e especificações
 
 ### Formato de Saída (Sempre Estruturado)
 
-Use o seguinte formato em comentários Jira:
+Use o seguinte formato nos comentários Jira (eles só saem depois da pergunta, regra de ouro):
 
 **Resumo da Revisão de Qualidade**
 

package/bin/README.md

@@ -7,11 +7,11 @@ Fonte do binário `jarvis` (instalado via `npm install -g jarvis-ai-framework`,
 ```
 bin/
 ├── jarvis.js                  # Entrypoint (shebang). ~10 linhas, não cresce.
-├── postinstall.js             # Roda no `npm install` (sincroniza assets se já havia .{ide}/ no cwd)
+├── postinstall.js             # Roda no `npm install` (só imprime as dicas de uso)
 ├── commands/                  # Um arquivo por comando. Lógica pura, zero commander.
 │   ├── init.js, list.js, info.js, whoami.js, ...
 │   ├── docs-sync.js, docs-publish.js
-│   └── qa-signoff.js, install-rtk.js, tokens.js, map.js
+│   └── install-rtk.js, tokens.js, map.js
 └── lib/
     ├── cli/
     │   ├── program.js         # Único lugar que monta o commander — ver "Arquitetura"
@@ -119,7 +119,7 @@ if (fileURLToPath(import.meta.url) === process.argv[1]) {
 
 ## Variáveis de ambiente lidas diretamente (fora do ENV.md)
 
-`bin/lib/tasks/comment.js` e `bin/lib/vcs/*.js` leem `process.env` direto (`TASK_MANAGER`, `TASK_MANAGER_ACCESS`, `TASK_MANAGER_URL_BASE`, `VERSION_CONTROL`, etc.; nenhum token: o login é o da CLI do vendor) — não passam pelo `env-loader.js`/ENV.md. O `jarvis tasks comment` e o `jarvis vcs create-merge` completam o que faltar no ambiente lendo o `$IDE/ENV.md` do workspace (`readFileEnv`/`resolveFileEnv` em `integrations/cli-runner.js`, com `--ide`/`--env-file`; o ambiente do processo vence; `setting` tira aspas e comentário de fim de linha), então os skills não precisam exportar nada nem usar `eval`. O `accessGate` decide antes de qualquer envio: só `cli` (ou vazio, com aviso) segue; `manual`, valor inválido e ENV.md ilegível saem com 3. O ENV.md lido é repassado ao `createMergeRequest` (`fileEnvResult`), inclusive pelo Central docs. Se um comando novo precisar ler o `ENV.md` diretamente, use `env-loader.js#resolveEnvPath`/`loadEnv` (ver `whoami.js`, `tokens.js`, `qa-signoff.js` como exemplo) em vez de `process.env`.
+`bin/lib/tasks/comment.js` e `bin/lib/vcs/*.js` leem `process.env` direto (`TASK_MANAGER`, `TASK_MANAGER_ACCESS`, `TASK_MANAGER_URL_BASE`, `VERSION_CONTROL`, etc.; nenhum token: o login é o da CLI do vendor) — não passam pelo `env-loader.js`/ENV.md. O `jarvis tasks comment` e o `jarvis vcs create-merge` completam o que faltar no ambiente lendo o `$IDE/ENV.md` do workspace (`readFileEnv`/`resolveFileEnv` em `integrations/cli-runner.js`, com `--ide`/`--env-file`; o ambiente do processo vence; `setting` tira aspas e comentário de fim de linha), então os skills não precisam exportar nada nem usar `eval`. O `accessGate` decide antes de qualquer envio: só `cli` (ou vazio, com aviso) segue; `manual`, valor inválido e ENV.md ilegível saem com 3. O ENV.md lido é repassado ao `createMergeRequest` (`fileEnvResult`), inclusive pelo Central docs. Se um comando novo precisar ler o `ENV.md` diretamente, use `env-loader.js#resolveEnvPath`/`loadEnv` (ver `whoami.js` e `tokens.js` como exemplo) em vez de `process.env`.
 
 ## Testes
 

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,
@@ -133,6 +134,10 @@ export async function init(flags) {
 
   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);
+
   // Reinstall: --force ou confirmação "s" devem sobrescrever assets (cpSync force:true).
   let forceSync = !!flags.force;
 
@@ -257,6 +262,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 +371,27 @@ async function runUpgrade(cwd, flags) {
   const workspaceDir = resolved.root;
   const envPath = resolved.path;
   const previousVersion = readLockVersion(workspaceDir);
+  const { downgrade, running } = 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`);

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";
@@ -93,7 +92,10 @@ export function buildProgram() {
       "--upgrade",
       "Atualiza um projeto já configurado: arquivos do framework, variáveis novas do ENV e pastas de documentos"
     )
-    .option("--yes", "Com --upgrade, move os documentos para as pastas novas sem perguntar")
+    .option(
+      "--yes",
+      "Com --upgrade, 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)"
@@ -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

@@ -575,7 +575,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.1.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",
     "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
 
 ---

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

@@ -9,7 +9,7 @@ O Jarvis não assume Jira, GitLab ou Slack. Leia `$IDE/ENV.md` e siga a cadeia d
 | Variável | Vendors | Como |
 |----------|---------|------|
 | `TASK_MANAGER` (+ `TASK_MANAGER_ACCESS`, `TASK_MANAGER_URL_BASE`) | jira (`acli`, só Cloud), github (`gh`), gitlab (`glab`) | `jarvis tasks comment` |
-| `VERSION_CONTROL` (+ `VERSION_CONTROL_ACCESS`) | github (`gh`), gitlab (`glab`); repo vem do `git remote` | `jarvis vcs create-merge` / `create-issue` |
+| `VERSION_CONTROL` (+ `VERSION_CONTROL_ACCESS`) | github (`gh`), gitlab (`glab`); no `create-merge` o repo vem do `git remote`, no `create-issue` vai em `--repo` | `jarvis vcs create-merge` / `create-issue` |
 | `CENTRAL_DOCS_STORAGE` | filesystem (s3 e gdrive no futuro) | `jarvis docs fetch` / `sync` / `publish` |
 | `MESSAGE_COMUNICATOR` | slack, discord, teams | runtime `communicator/` |
 
@@ -41,11 +41,15 @@ Qual o seu número de controle para esta tarefa?
 
 Com board definido, se o key não veio nos argumentos, perguntar o id do card naquele vendor (ex: Jira `TASK-123`, GitHub `#42`).
 
+## Nada é publicado sem perguntar
+
+É a **regra de ouro**: comentário, PR/MR, issue, push e publicação no Central docs só saem depois de mostrar o texto e perguntar, na hora do envio, com `AskUserQuestion` (sem a ferramenta, a tabela de `prod-rules.md`): **Sim, publicar** / **Não, manter só na sessão** (rótulos equivalentes por contexto). A pergunta vale para cada envio; uma aprovação não vale para o próximo. **Exceção:** documentos aprovados juntos (como a consolidação do `eng.spec-consolidate`) são um envio; e a escolha da Fase 0 do `eng.pr` vale como a pergunta do push e do PR e, conforme a opção, como a revisão do texto. Sem o Sim, o texto fica na sessão (`task-comment-{YYYYMMDD-HHMM}.md`, `pull-request.md`) ou em `.jarvis/issues/`, e o push fica só local.
+
 ## Comentário no card
 
 Falha no comentário não bloqueia o workflow.
 
-Comentar **somente** em eventos relevantes: (a) **desvio do plano** (mudança de direção, fase bloqueada), (b) **auditoria do Advisor** (as questões do `architecture.md` com as opções junto da escolha), (c) **bloqueio** com valor de rastreabilidade, (d) **link do MR**, uma única vez, (e) o **`gate-checklist.md` do `eng.pre-pr`**, só se o usuário escolher registrar (resumo ou relatório completo). **Nunca** comentar início ou fim de etapa ("Iniciando…", "concluído…"): o acompanhamento fica no fluxo e no PR.
+Comentar **somente** em eventos relevantes, **cada um depois da pergunta acima**: (a) **desvio do plano** (mudança de direção, fase bloqueada), (b) **auditoria do Advisor** (as questões do `architecture.md` com as opções junto da escolha), (c) **bloqueio** com valor de rastreabilidade, (d) **link do MR**, uma única vez, (e) o **`gate-checklist.md` do `eng.pre-pr`**, só se o usuário escolher registrar (resumo ou relatório completo), (f) a arquitetura do **`eng.light-arch`**, depois de aprovada, (g) outro comentário que o fluxo peça e você aprove (como o de refinamento do agente de QA e o da 7.4 do `delivery-spec`). **Nunca** comentar início ou fim de etapa ("Iniciando…", "concluído…"): o acompanhamento fica no fluxo e no PR.
 
 ```
 /eng-global-task-comment {TASK_MANAGER_KEY} {mensagem}

package/rules/rtk-rules.md

@@ -60,7 +60,7 @@ cargo install brokk-rtk
 cargo install rtk  # ❌ Isso instala Rust Type Kit, não Token Killer
 ```
 
-Use o comando `npx jarvis install-rtk` que valida e instala a ferramenta correta automaticamente.
+Use o comando `jarvis install-rtk` que valida e instala a ferramenta correta automaticamente.
 
 ---
 

package/rules-on-demand/doc-links-rules.md

@@ -12,7 +12,7 @@ Lida pelo comando antes de escrever o documento. A tabela mostra quem lê:
 
 | Documento | Comando |
 |---|---|
-| `architecture.md`, `plan.md` (inclusive os comentários de fase), `gate-checklist.md`, `pull-request.md` | `eng.start`, `eng.plan`, `eng.work`, `eng.pre-pr`, `eng.pr` |
+| `architecture.md`, `plan.md` (inclusive os comentários de fase), `gate-checklist.md` (e as rodadas anteriores `gate-checklist-rodada-{N}.md`), `pull-request.md` | `eng.start`, `eng.plan`, `eng.work`, `eng.pre-pr`, `eng.pr` |
 | PRD, FRD, épico, história/tarefa, discovery, breakdown | `prod.spec.prd`, `prod.spec.frd`, `prod.spec.epic`, `prod.spec.issue`, `prod.spec.discovery`, `prod.spec.breakdown`, `prod.spec.clarify` |
 | ARD, RFC, SPEC | `prod.spec.ard`, `eng.create-ard`, `eng.create-ard-from-code`, `eng.create-rfc`, `eng.build-tech-spec` |
 | Outros documentos gravados por comando (subtarefas, arquitetura leve, relatório de investigação, documentação do repositório (regra 7), revisão, robô, Central docs) | `eng.breakdown-subtasks`, `eng.light-arch`, `eng.debug`, `eng.docs`, `eng.review`, `eng.rpa.robot`, `eng.spec-consolidate` |
@@ -52,7 +52,7 @@ Lida pelo comando antes de escrever o documento. A tabela mostra quem lê:
    - Issue, PR e card como URL.
    - Código como `{remote}/blob/{sha}/{caminho}#L{n}` (GitLab: `{remote}/-/blob/{sha}/…`). O trecho é `#L{a}-L{b}` no GitHub e `#L{a}-{b}` no GitLab.
    - Sessão e `docs/jarvis/` em texto, sem link: quem lê fora do workspace não abre esses arquivos.
-   - O `{sha}` é o `HEAD` no momento em que o `eng.pr` escreve o `pull-request.md` (Fase 4.1). Se a conferência de marcas (Fase 3.0) reescrever commits, atualize o sha dos links. Com "Só gerar os arquivos", os links valem quando o push for feito sem rebase.
+   - O `{sha}` é o `HEAD` no momento em que o `eng.pr` escreve o `pull-request.md` (Fase 4.1). Se a conferência de marcas (Fase 3.0) reescrever commits, atualize o sha dos links. Com "Só gerar os arquivos" (na Fase 0 ou na revisão da 4.2), os links valem quando o push for feito sem rebase.
    - No Central docs, o `{sha}` é o do merge na branch base (a consolidação roda depois do merge).
    - No `.public.md` (gerado no fim do próprio comando, muitas vezes sem push), o `{sha}` é o último commit já enviado ao remoto (`git rev-parse @{u}`), ou o sha do cabeçalho se ele já estiver no remoto. Sem nenhum dos dois, o código fica em texto.
 7. **Documento versionado no repositório** (`README.md`, `docs/` do projeto, gravados por exemplo pelo `eng.docs`): o caminho é relativo dentro do próprio repositório (nada de subir até o workspace com `../../{repo}/…`), porque ele é lido no GitHub/GitLab. A sessão e o `docs/jarvis/` ficam em texto, sem link.