jarvis-ai-framework 5.2.0 → 5.5.0

package/AGENTS.md

@@ -194,6 +194,7 @@ Comandos disponíveis:
 jarvis whoami   [--logout]                          # Exibir identidade (ENV.md / git / SO)
 jarvis logout                                       # Remover auth.json legado (opcional)
 jarvis init                                         # Bootstrap do framework no projeto
+jarvis init --upgrade [--ide X] [--yes]             # Atualizar projeto existente: assets + variáveis novas do ENV + documentos nas pastas novas
 jarvis list                                         # Listar agents, skills e workflows
 jarvis install-rtk                                  # Instalar RTK (token killer — economia 60-90% em tokens de shell)
 jarvis tokens    [--hub X --position Y --area Z --squad W] [--rtk] [--json]   # Estimar o que carrega no início da sessão (perfil do ENV.md se sem flags)

package/README.md

@@ -116,9 +116,11 @@ Mesmos passos 2 e 3 do [Get Started](#get-started) acima — `jarvis init --ide
 
 ```bash
 npm install -g jarvis-ai-framework@latest
-jarvis init --ide {ide}   # re-sincroniza os assets (agents/skills/workflows/rules)
+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).
+
 **Instalou via clone local** (fluxo de [Desenvolvendo o Jarvis localmente](#desenvolvendo-o-jarvis-localmente)) — quando o repo no GitHub ganhar commits novos, sincronize assim:
 
 ### 1. Atualizar o clone
@@ -203,6 +205,17 @@ Escolha **Upgrade (C)** — adiciona chaves novas do template sem apagar os valo
 
 ---
 
+## Estilo dos artefatos
+
+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 |
+
+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`.
+
 ## Funciona com qualquer stack
 
 O Jarvis não presume Go, PHP, NestJS ou React. Cada área (backend e frontend) tem uma **skill base neutra**, e cada projeto registra no `ENV.md` as **especializações** da sua stack (`BACKEND_SPECIALIZATIONS` e `FRONTEND_SPECIALIZATIONS`). Os comandos `eng.*` carregam a base mais o que o projeto registrou.

package/bin/commands/init.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, dirname, basename } from "node:path";
 import { createInterface } from "node:readline";
 import { syncAssets } from "../lib/core/sync-engine.js";
 import { discoverAll } from "../lib/core/scanner.js";
@@ -7,12 +7,23 @@ import {
   IDES,
   getIDEConfig,
   getIDEFolder,
+  getIDEValues,
   getWorkflowsFolder,
   isIDESupported,
 } from "../lib/config/ide-config.js";
 import { showBanner, RED, GREEN, BLUE, YELLOW, CYAN, DIM, BOLD, NC } from "../lib/utils/ui.js";
-import { getPackageInfo } from "../lib/utils/paths.js";
+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 { parseEnvEntries, planEnvUpgrade, applyEnvUpgrade } from "../lib/core/env-upgrade.js";
+import {
+  expandEnv,
+  planDocsMigration,
+  applyDocsMigration,
+  rewriteRelatedDiscovery,
+  declineEnvValues,
+} from "../lib/core/docs-migrate.js";
 
 function ask(rl, question) {
   return new Promise((resolve) => rl.question(question, resolve));
@@ -25,6 +36,11 @@ export async function init(flags) {
 
   showBanner();
 
+  if (flags.upgrade) {
+    process.exitCode = await runUpgrade(cwd, flags);
+    return;
+  }
+
   let ide;
   if (flags.ide) {
     if (!isIDESupported(flags.ide)) {
@@ -207,3 +223,134 @@ export async function init(flags) {
   logger.info(`     ${YELLOW}jarvis list${NC}`);
   logger.info("");
 }
+
+/** IDE de um ENV.md encontrado (`.claude/ENV.md` → `claude`). */
+function ideFromEnvPath(envPath) {
+  const folder = basename(dirname(envPath));
+  return getIDEValues().find((v) => `.${getIDEFolder(v)}` === folder);
+}
+
+function readLockVersion(workspaceDir) {
+  try {
+    return (
+      JSON.parse(readFileSync(join(workspaceDir, LOCK_FILE), "utf-8")).version || "desconhecida"
+    );
+  } catch {
+    return "desconhecida";
+  }
+}
+
+/**
+ * `jarvis init --upgrade`: atualiza um projeto já configurado em uma passada.
+ * 1. arquivos do framework (como o --force, sem perguntar); 2. só as chaves novas do ENV;
+ * 3. documentos dos caminhos antigos → docs/jarvis/… (com confirmação ou --yes).
+ * Nunca imprime valores do ENV, só nomes de chave e caminhos.
+ * @returns {Promise<number>} código de saída
+ */
+async function runUpgrade(cwd, flags) {
+  let resolved;
+  try {
+    resolved = resolveEnvPath(cwd, flags.ide ? { ide: flags.ide } : {});
+  } catch (err) {
+    resolved = { error: err.message.split("\n")[0] };
+  }
+  const ide = flags.ide || (resolved.path && ideFromEnvPath(resolved.path));
+  if (resolved.error || !ide || !existsSync(resolved.path)) {
+    logger.error(
+      `${RED}🚫 Nenhuma instalação do Jarvis encontrada (ENV.md ausente)${resolved.error ? `: ${resolved.error}` : ""}.${NC}`
+    );
+    logger.error(
+      `${YELLOW}Rode ${BOLD}jarvis init --ide ${flags.ide || "{ide}"}${NC}${YELLOW} e depois ${BOLD}/jarvis-init${NC}${YELLOW} na IDE.${NC}\n`
+    );
+    return 1;
+  }
+  const workspaceDir = resolved.root;
+  const envPath = resolved.path;
+  const previousVersion = readLockVersion(workspaceDir);
+
+  // 1. Arquivos do framework (o ENV.md não está entre os sincronizados)
+  logger.info(`${BLUE}⬆️  Upgrade do Jarvis em .${getIDEFolder(ide)}/${NC}\n`);
+  const sync = syncAssets(workspaceDir, ide, {
+    force: true,
+    workflowsFolder: getWorkflowsFolder(ide),
+    keepEnvValues: true,
+  });
+  for (const item of sync.errors) logger.error(`${RED}  ✗ ${item}${NC}`);
+
+  // 2. Variáveis novas (só acrescenta)
+  const envText = readFileSync(envPath, "utf-8");
+  const templateText = readFileSync(
+    join(getFrameworkRoot(), "templates", "ENV-template.md"),
+    "utf-8"
+  );
+  const envPlan = planEnvUpgrade(envText, templateText);
+  const addedKeys = envPlan.added.map((a) => a.key);
+
+  // 3. Documentos: o plano usa o ENV como ficará depois do upgrade (com as chaves novas)
+  const futureEntries = parseEnvEntries(
+    `${envText}\n${envPlan.added.map(({ key, value }) => `${key}=${value}`).join("\n")}\n`
+  );
+  const env = expandEnv(futureEntries);
+  const docsPlan = planDocsMigration(workspaceDir, env);
+
+  let accepted = false;
+  if (docsPlan.moves.length > 0) {
+    logger.info(`${YELLOW}📁 Documentos em caminhos antigos:${NC}`);
+    for (const m of docsPlan.moves) logger.info(`  ${m.from} → ${m.to}`);
+    if (flags.yes) accepted = true;
+    else if (process.stdin.isTTY) {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await ask(rl, `Mover para docs/jarvis/…? (s/N): `);
+      rl.close();
+      accepted = answer.trim().toLowerCase() === "s";
+    } else {
+      logger.info(`${DIM}  Sem terminal interativo e sem --yes: nada será movido.${NC}`);
+    }
+  }
+
+  const overrides =
+    docsPlan.moves.length > 0 && !accepted ? declineEnvValues(docsPlan, addedKeys, env) : {};
+  const today = new Date().toISOString().slice(0, 10);
+  applyEnvUpgrade(envPath, envPlan, today, overrides);
+
+  let moved = [];
+  let rewritten = [];
+  let moveErrors = [];
+  if (accepted) {
+    const result = applyDocsMigration(workspaceDir, docsPlan, env);
+    moved = result.moved;
+    moveErrors = result.errors;
+    rewritten = rewriteRelatedDiscovery(workspaceDir, env, moved);
+  }
+
+  // 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(`  • Arquivos do framework: ${sync.copied.length} item(ns) sincronizado(s)`);
+  logger.info(
+    `  • ENV.md: ${addedKeys.length ? `+ ${addedKeys.join(", ")}` : "nenhuma variável nova"}`
+  );
+  if (Object.keys(overrides).length) {
+    logger.info(`  • Mantidos no caminho antigo: ${Object.keys(overrides).join(", ")}`);
+  }
+  if (docsPlan.moves.length && !accepted) {
+    logger.info(`  • Documentos: nada movido (${docsPlan.moves.length} no caminho antigo)`);
+  }
+  if (moved.length) logger.info(`  • Documentos movidos: ${moved.length}`);
+  if (rewritten.length) logger.info(`  • related_discovery atualizado: ${rewritten.join(", ")}`);
+  for (const s of docsPlan.skipped)
+    logger.info(`${YELLOW}  ⚠️  Pulado (${s.reason}): ${s.from}${NC}`);
+  for (const e of moveErrors) logger.error(`${RED}  ✗ ${e}${NC}`);
+  for (const k of envPlan.pending) {
+    logger.info(`${YELLOW}  ⚠️  ${k} está vazio: responda no /jarvis-init upgrade${NC}`);
+  }
+  if (envPlan.warnings.includes("CENTRAL_DOCS_REPO")) {
+    logger.info(
+      `${YELLOW}  ⚠️  Central docs no formato antigo (CENTRAL_DOCS_REPO): a migração é feita pelo /jarvis-init upgrade${NC}`
+    );
+  }
+  logger.info("");
+  logger.info(`${CYAN}➡️  Agora rode ${BOLD}/jarvis-init upgrade${NC}${CYAN} na IDE.${NC}\n`);
+  return sync.errors.length || moveErrors.length ? 1 : 0;
+}

package/bin/commands/tokens.js

@@ -6,16 +6,20 @@ import { logger } from "../lib/utils/logger.js";
 
 const AXES = ["HUB", "POSITION", "AREA", "SQUAD"];
 
-/** Perfil: as flags (`--hub` etc.) mandam; o que faltar vem do ENV.md. */
+/**
+ * Perfil: as flags (`--hub` etc.) mandam; o que faltar vem do ENV.md.
+ * ARTIFACT_STYLE é opcional (vazio = ai-generated) e não entra em `missing`.
+ */
 function resolveProfile(flags) {
   const profile = {};
   for (const axis of AXES) {
     const value = flags[axis.toLowerCase()];
     if (typeof value === "string") profile[axis] = value;
   }
+  if (typeof flags.artifactStyle === "string") profile.ARTIFACT_STYLE = flags.artifactStyle;
 
   let rtkEnabled = flags.rtk === true || flags.rtk === "true";
-  // O ENV.md só entra quando falta algum eixo; com os 4 eixos nas flags, o RTK vem só da flag.
+  // O ENV.md só entra quando falta algum eixo; com os 4 eixos nas flags, o RTK e o estilo vêm só das flags.
   if (AXES.some((axis) => !profile[axis])) {
     try {
       const { path } = resolveEnvPath(process.cwd(), flags);
@@ -23,6 +27,8 @@ function resolveProfile(flags) {
       for (const axis of AXES) {
         if (!profile[axis] && env[axis]) profile[axis] = env[axis];
       }
+      if (!profile.ARTIFACT_STYLE && env.ARTIFACT_STYLE)
+        profile.ARTIFACT_STYLE = env.ARTIFACT_STYLE;
       if (flags.rtk === undefined) rtkEnabled = env.RTK_ENABLED === "true";
     } catch {
       // sem ENV.md: valem só as flags
@@ -59,7 +65,7 @@ export async function tokens(flags) {
   showBanner();
   logger.info(`${CYAN}📏 Custo estimado no início da sessão${NC}`);
   logger.info(
-    `${DIM}Perfil: HUB=${profile.HUB} | POSITION=${profile.POSITION} | AREA=${profile.AREA} | SQUAD=${profile.SQUAD}` +
+    `${DIM}Perfil: HUB=${profile.HUB} | POSITION=${profile.POSITION} | AREA=${profile.AREA} | SQUAD=${profile.SQUAD} | ARTIFACT_STYLE=${profile.ARTIFACT_STYLE || "ai-generated"}` +
       ` | RTK=${rtkEnabled ? "ligado" : "desligado"}${NC}`
   );
   logger.info(`${DIM}${report.estimate}${NC}`);

package/bin/lib/cli/program.js

@@ -87,7 +87,12 @@ 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", "Sobrescreve a instalação existente sem perguntar")
+    .option(
+      "--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");
   withLogOptions(initCmd).action((options) => init(toLegacyFlags(options)));
 
   cmd(program, "list")
@@ -164,6 +169,7 @@ export function buildProgram() {
     .option("--position <position>")
     .option("--area <area>")
     .option("--squad <squad>")
+    .option("--artifact-style <estilo>", "ai-generated ou human-generated (padrão: lido do ENV.md)")
     .option("--rtk", "Força RTK ligado (padrão: lido do ENV.md)")
     .option("--json", "Saída em JSON")
     .option("--ide <ide>")
@@ -201,8 +207,14 @@ export function buildProgram() {
     .option("--repo <url-ou-path>")
     .option("--title <titulo>")
     .option("--body-file <path>")
+    .option("--label <labels>", "Labels separadas por vírgula (padrão: bug)")
     .action((options) =>
-      runCreateIssue({ repo: options.repo, title: options.title, bodyFile: options.bodyFile })
+      runCreateIssue({
+        repo: options.repo,
+        title: options.title,
+        bodyFile: options.bodyFile,
+        labels: options.label,
+      })
     );
 
   const tasks = cmd(program, "tasks").description("Adapters de task manager");

package/bin/lib/core/docs-migrate.js

@@ -0,0 +1,259 @@
+// Documentos de trabalho nos caminhos antigos → docs/jarvis/… (`jarvis init --upgrade`).
+// Mesmas regras do item 8 do Upgrade (C) do skill jarvis-init: conflito no destino pula,
+// pasta antiga removida só se ficar vazia, `git mv` quando versionado, `related_discovery`
+// reescrito pelo nome do arquivo e, na recusa, só chaves novas recebem o caminho antigo.
+import {
+  existsSync,
+  readdirSync,
+  statSync,
+  mkdirSync,
+  renameSync,
+  rmdirSync,
+  readFileSync,
+  writeFileSync,
+  appendFileSync,
+} from "node:fs";
+import { join, resolve, relative, dirname, basename, isAbsolute, sep } from "node:path";
+import { execFileSync } from "node:child_process";
+
+const ENG_SUBDIRS = ["ARD", "RFC", "qa", "swagger", "openapi", "robots", "c4"];
+const LEGACY_ENG_SUBDIRS = ["robots", "swagger", "openapi", "c4"];
+
+/**
+ * Resolve `$NOME` com as outras chaves do ENV, **em qualquer ordem**: upgrades antigos
+ * acrescentaram `JARVIS_DOCS` no fim do arquivo, depois do `PROD_DOCS` que a usa.
+ * Desconhecida (ex.: `$IDE`) ou ciclo fica literal.
+ * @param {Map<string, string>} entries
+ * @returns {Map<string, string>}
+ */
+export function expandEnv(entries) {
+  const out = new Map();
+  const resolving = new Set();
+  const resolveKey = (key) => {
+    if (out.has(key)) return out.get(key);
+    if (!entries.has(key) || resolving.has(key)) return null;
+    resolving.add(key);
+    const value = entries
+      .get(key)
+      .replace(/\$([A-Z][A-Z0-9_]*)/g, (m, name) => resolveKey(name) ?? m);
+    resolving.delete(key);
+    out.set(key, value);
+    return value;
+  };
+  for (const key of entries.keys()) resolveKey(key);
+  return out;
+}
+
+const clean = (p) => p.replace(/^\.\//, "").replace(/\/+$/, "");
+
+/** Pastas de documentos resolvidas, com os padrões do template quando faltam. */
+export function docsFolders(env) {
+  const docs = clean(env.get("DOCS_FOLDER") || "docs");
+  const jarvis = clean(env.get("JARVIS_DOCS") || `${docs}/jarvis`);
+  const prod = clean(env.get("PROD_DOCS") || `${jarvis}/product`);
+  const eng = clean(env.get("ENG_DOCS") || `${jarvis}/engineering`);
+  const discoveries = clean(env.get("DISCOVERIES_DOCS") || `${jarvis}/discoveries`);
+  return { docs, jarvis, prod, eng, discoveries };
+}
+
+function inside(workspaceDir, rel) {
+  if (isAbsolute(rel)) return false;
+  const r = relative(workspaceDir, resolve(workspaceDir, rel));
+  return r !== "" && !r.startsWith("..") && !isAbsolute(r);
+}
+
+function listFiles(dir) {
+  const files = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...listFiles(p));
+    else if (entry.isFile()) files.push(p);
+  }
+  return files;
+}
+
+/** Pares pasta antiga → pasta nova, na ordem do item 8 + discoveries. */
+function sourcePairs(f) {
+  const pairs = [
+    { from: `${f.docs}/product`, to: f.prod, discoveriesSub: true },
+    ...ENG_SUBDIRS.map((s) => ({ from: `${f.docs}/engineering/${s}`, to: `${f.eng}/${s}` })),
+    ...LEGACY_ENG_SUBDIRS.map((s) => ({ from: `docs/engineering/${s}`, to: `${f.eng}/${s}` })),
+    { from: `${f.prod}/discoveries`, to: f.discoveries, discovery: true },
+  ];
+  const seen = new Set();
+  return pairs.filter((p) => {
+    if (p.from === p.to || seen.has(p.from)) return false;
+    seen.add(p.from);
+    return true;
+  });
+}
+
+/**
+ * Planeja a mudança de pasta (sem mexer em nada).
+ * @param {string} workspaceDir — pasta que contém `.{ide}/`
+ * @param {Map<string, string>} env — ENV já expandido (`expandEnv`)
+ * @returns {{ moves: {from: string, to: string, discovery: boolean}[],
+ *   skipped: {from: string, to: string, reason: string}[], sources: string[] }}
+ *   Caminhos relativos ao workspace.
+ */
+export function planDocsMigration(workspaceDir, env) {
+  const f = docsFolders(env);
+  const moves = [];
+  const skipped = [];
+  const sources = [];
+
+  for (const pair of sourcePairs(f)) {
+    if (!inside(workspaceDir, pair.from) || !inside(workspaceDir, pair.to)) {
+      skipped.push({ from: pair.from, to: pair.to, reason: "fora do workspace" });
+      continue;
+    }
+    const fromAbs = join(workspaceDir, pair.from);
+    if (!existsSync(fromAbs) || !statSync(fromAbs).isDirectory()) continue;
+
+    let added = false;
+    for (const fileAbs of listFiles(fromAbs)) {
+      const rel = relative(fromAbs, fileAbs).split(sep).join("/");
+      // docs/product/discoveries/* (layout antigo) vai direto para a pasta dos discoveries
+      const toDiscoveries =
+        pair.discovery || (pair.discoveriesSub && rel.startsWith("discoveries/"));
+      const to = toDiscoveries
+        ? `${f.discoveries}/${pair.discovery ? rel : rel.slice("discoveries/".length)}`
+        : `${pair.to}/${rel}`;
+      const from = `${pair.from}/${rel}`;
+      if (from === to) continue;
+      if (existsSync(join(workspaceDir, to)) || moves.some((m) => m.to === to)) {
+        skipped.push({ from, to, reason: "conflito" });
+        continue;
+      }
+      moves.push({ from, to, discovery: toDiscoveries });
+      added = true;
+    }
+    if (added) sources.push(pair.from);
+  }
+  return { moves, skipped, sources };
+}
+
+function isTracked(fileAbs) {
+  try {
+    execFileSync("git", ["ls-files", "--error-unmatch", basename(fileAbs)], {
+      cwd: dirname(fileAbs),
+      stdio: "ignore",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function removeEmptyDirs(dirAbs, stopAbs) {
+  let dir = dirAbs;
+  while (dir.startsWith(stopAbs) && dir !== stopAbs && existsSync(dir)) {
+    if (readdirSync(dir).length > 0) break;
+    rmdirSync(dir);
+    dir = dirname(dir);
+  }
+}
+
+function emptyDirsUnder(dirAbs) {
+  if (!existsSync(dirAbs)) return;
+  for (const entry of readdirSync(dirAbs, { withFileTypes: true })) {
+    if (entry.isDirectory()) emptyDirsUnder(join(dirAbs, entry.name));
+  }
+  if (readdirSync(dirAbs).length === 0) rmdirSync(dirAbs);
+}
+
+/**
+ * Aplica o plano: `git mv` se o arquivo é versionado, senão `rename`. Remove as pastas
+ * antigas só se ficarem vazias e garante `{JARVIS_DOCS}/` no `.gitignore` do workspace.
+ * @returns {{ moved: {from: string, to: string, discovery: boolean}[], errors: string[] }}
+ */
+export function applyDocsMigration(workspaceDir, plan, env) {
+  const moved = [];
+  const errors = [];
+  for (const m of plan.moves) {
+    const fromAbs = join(workspaceDir, m.from);
+    const toAbs = join(workspaceDir, m.to);
+    try {
+      mkdirSync(dirname(toAbs), { recursive: true });
+      if (isTracked(fromAbs)) {
+        execFileSync("git", ["mv", fromAbs, toAbs], { cwd: dirname(fromAbs), stdio: "ignore" });
+      } else {
+        renameSync(fromAbs, toAbs);
+      }
+      moved.push(m);
+    } catch (err) {
+      errors.push(`${m.from}: ${err.message.split("\n")[0]}`);
+    }
+  }
+
+  // Pastas antigas vazias saem; a pasta raiz dos documentos ($DOCS_FOLDER) sempre fica.
+  const docsAbs = join(workspaceDir, docsFolders(env).docs);
+  for (const src of plan.sources) {
+    const srcAbs = join(workspaceDir, src);
+    emptyDirsUnder(srcAbs);
+    removeEmptyDirs(dirname(srcAbs), docsAbs);
+  }
+
+  if (moved.length > 0) ensureGitignore(workspaceDir, `${docsFolders(env).jarvis}/`);
+  return { moved, errors };
+}
+
+function ensureGitignore(workspaceDir, line) {
+  const p = join(workspaceDir, ".gitignore");
+  const text = existsSync(p) ? readFileSync(p, "utf-8") : "";
+  const bare = line.replace(/\/$/, "");
+  if (text.split("\n").some((l) => [line, bare, `/${line}`, `/${bare}`].includes(l.trim()))) return;
+  appendFileSync(p, `${text && !text.endsWith("\n") ? "\n" : ""}${line}\n`);
+}
+
+/**
+ * Nos `.md` de `PROD_DOCS`, todo `related_discovery:` cujo nome de arquivo seja o de um
+ * discovery movido passa ao caminho novo — inclusive valores que já estavam quebrados.
+ * @returns {string[]} arquivos alterados (relativos ao workspace)
+ */
+export function rewriteRelatedDiscovery(workspaceDir, env, moved) {
+  const byName = new Map(moved.filter((m) => m.discovery).map((m) => [basename(m.to), m.to]));
+  if (byName.size === 0) return [];
+  const prodAbs = join(workspaceDir, docsFolders(env).prod);
+  if (!existsSync(prodAbs)) return [];
+
+  const changed = [];
+  for (const fileAbs of listFiles(prodAbs).filter((p) => p.endsWith(".md"))) {
+    const text = readFileSync(fileAbs, "utf-8");
+    const next = text.replace(
+      /^(related_discovery:[ \t]*)(\S+)[ \t]*$/gm,
+      (line, prefix, value) => {
+        const to = byName.get(basename(value));
+        return to && value !== to ? `${prefix}${to}` : line;
+      }
+    );
+    if (next !== text) {
+      writeFileSync(fileAbs, next);
+      changed.push(relative(workspaceDir, fileAbs).split(sep).join("/"));
+    }
+  }
+  return changed;
+}
+
+/**
+ * Recusa em mover: o valor que as chaves **novas** recebem para continuar no caminho antigo.
+ * Chave que já existe no ENV não muda (o upgrade só acrescenta).
+ * @param {{moves: {from: string, discovery: boolean}[]}} plan
+ * @param {string[]} addedKeys — chaves que o upgrade vai acrescentar
+ * @returns {Record<string, string>}
+ */
+export function declineEnvValues(plan, addedKeys, env) {
+  const added = new Set(addedKeys);
+  const f = docsFolders(env);
+  const out = {};
+  if (added.has("DISCOVERIES_DOCS") && plan.moves.some((m) => m.discovery)) {
+    out.DISCOVERIES_DOCS = "$PROD_DOCS/discoveries";
+  }
+  if (added.has("PROD_DOCS") && plan.moves.some((m) => m.from.startsWith(`${f.docs}/product/`))) {
+    out.PROD_DOCS = "$DOCS_FOLDER/product";
+  }
+  if (added.has("ENG_DOCS") && plan.moves.some((m) => m.from.includes("/engineering/"))) {
+    out.ENG_DOCS = "$DOCS_FOLDER/engineering";
+  }
+  return out;
+}

package/bin/lib/core/env-upgrade.js

@@ -0,0 +1,84 @@
+// Upgrade do ENV.md (`jarvis init --upgrade`): acrescenta as chaves do template que faltam.
+// Regra: só acrescenta. Nenhuma chave existente muda, preenchida, vazia ou com lista de opções.
+// Mesmas regras do Upgrade (C) do skill jarvis-init (itens 4, 5, 9, 10 e 11).
+import { readFileSync, writeFileSync } from "node:fs";
+
+const KEY_LINE = /^([A-Z][A-Z0-9_]*)=(.*)$/;
+
+// PROD_MODE nova: o valor vem da AREA (só no upgrade; a criação do ENV continua perguntando).
+const PROD_MODE_BY_AREA = { ENGINEERING: "developer-guided", PRODUCT: "product-led" };
+
+/**
+ * Lê as chaves do ENV na ordem do arquivo, **incluindo as vazias** (o `loadEnv`
+ * descarta as vazias, o que esconderia uma chave existente do diff).
+ * Linhas comentadas não contam.
+ * @returns {Map<string, string>}
+ */
+export function parseEnvEntries(text) {
+  const entries = new Map();
+  for (const line of text.split("\n")) {
+    const m = line.trim().match(KEY_LINE);
+    if (m && !entries.has(m[1])) entries.set(m[1], m[2].trim());
+  }
+  return entries;
+}
+
+function isOptionList(value) {
+  return /^\[.*\]$/.test(value);
+}
+
+// Bloco "Data Engineering": DATA_* só entram com HUB=DATA. DATA_SPECIALIZATIONS é
+// obrigatória em qualquer HUB (eng.specializations-rules.md) e nunca é excluída.
+function isDataOnlyKey(key) {
+  return key.startsWith("DATA_") && key !== "DATA_SPECIALIZATIONS";
+}
+
+/**
+ * Calcula o que o upgrade acrescenta, sem gravar nada.
+ * @returns {{ added: {key: string, value: string}[], pending: string[], warnings: string[] }}
+ *   `pending` e `warnings` trazem só nomes de chave, nunca valores do ENV.
+ */
+export function planEnvUpgrade(envText, templateText) {
+  const env = parseEnvEntries(envText);
+  const template = parseEnvEntries(templateText);
+  const hub = (env.get("HUB") || "").toUpperCase();
+  const area = (env.get("AREA") || "").toUpperCase();
+
+  const added = [];
+  const pending = [];
+  const warnings = [];
+
+  for (const [key, templateValue] of template) {
+    if (env.has(key)) continue;
+    if (hub !== "DATA" && isDataOnlyKey(key)) continue;
+
+    let value = isOptionList(templateValue) ? "" : templateValue;
+    if (key === "PROD_MODE") {
+      value = PROD_MODE_BY_AREA[area] || "";
+      if (!value) pending.push("PROD_MODE");
+    }
+    added.push({ key, value });
+  }
+
+  if (env.has("PROD_MODE") && !env.get("PROD_MODE")) pending.push("PROD_MODE");
+
+  if (env.get("CENTRAL_DOCS_REPO") && !env.has("CENTRAL_DOCS_STORAGE")) {
+    warnings.push("CENTRAL_DOCS_REPO");
+  }
+
+  return { added, pending, warnings };
+}
+
+/**
+ * Grava as chaves novas no fim do ENV, num bloco datado. Nenhuma linha existente muda.
+ * `overrides` troca o valor de chaves novas (ex.: recusa em mover os discoveries).
+ * @returns {boolean} true se gravou
+ */
+export function applyEnvUpgrade(envPath, plan, today, overrides = {}) {
+  if (plan.added.length === 0) return false;
+  const text = readFileSync(envPath, "utf-8");
+  const lines = plan.added.map(({ key, value }) => `${key}=${overrides[key] ?? value}`);
+  const sep = text.endsWith("\n") ? "" : "\n";
+  writeFileSync(envPath, `${text}${sep}\n# --- Upgrade ${today} ---\n${lines.join("\n")}\n`);
+  return true;
+}