jarvis-ai-framework 8.2.0 → 8.3.0

package/AGENTS.md

@@ -63,6 +63,7 @@ prompts/
 │   │   ├── eng-qa/                 # Base neutra de QA (+ especializações em QA_SPECIALIZATIONS)
 │   │   ├── eng-qa-planner/         # Planejamento de testes e análise de gaps de cobertura
 │   │   ├── jarvis-report-issue/          # Auto-report de bugs no repo do Jarvis (CLI do host: gh)
+│   │   ├── jarvis-fork/                  # Fork guiado de um artefato do core para o overlay da empresa (COMPANY_PROFILE; CLI jarvis fork)
 │   │   ├── eng-global-task-comment/      # Comentário no card (Jira/GitHub/GitLab, pela CLI do vendor)
 │   │   ├── jarvis-list-specializations/ # Lista especializações de stack instaladas e registradas
 │   │   ├── jarvis-create-specialization/ # Cria uma especialização de stack a partir do código do projeto e a registra
@@ -199,6 +200,7 @@ jarvis list                                         # Listar agents, skills e wo
 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)
 jarvis map       <nome> [--depth N] [--reverse]      # Mapa de chamadas de um workflow, skill ou agente (lê só as tabelas padronizadas)
+jarvis fork      [nome] [--list] [--update [--diff]] [--delete] [--candidate]   # Overlay de empresa (#199): copia um artefato do core para $IDE/overlays/{COMPANY_PROFILE}/ com carimbo; lista; recarimba; remove
 jarvis daily-report [--days N] [--json]             # Junta os daily.md das sessões por dia (usado pelo /eng.daily-report)
 ```
 

package/README.md

@@ -205,6 +205,17 @@ Guia completo: [`docs/especializacoes-de-stack.md`](docs/especializacoes-de-stac
 
 ---
 
+## Funciona com qualquer empresa
+
+A stack vem do código; o **processo** vem da empresa, e muda de cliente para cliente: de onde nasce a branch, como se entrega, quais gates valem, campos do MR. `COMPANY_PROFILE` no `ENV.md` (nasce como `stark-industries`, o overlay padrão) aponta para `.{ide}/overlays/{perfil}/`, uma pasta que espelha o core e guarda só o que a empresa substituiu. O `jarvis init --upgrade` atualiza o core e nunca grava arquivo no overlay.
+
+- **`/jarvis-fork {artefato}`**: uma conversa até achar a seção do core que não serve, o menor ajuste, a simulação e o fork no overlay, só com o Sim; `--list`, `--update`, `--delete`
+- **Dois resolvers**: uma rule universal confere o overlay na chamada (workflows, skills, agentes, templates); o `jarvis init` e o `/jarvis-init` copiam por cima as `rules/` do overlay na instalação
+
+Guia completo: [`docs/overlay-de-empresa.md`](docs/overlay-de-empresa.md).
+
+---
+
 ## Camadas
 
 O Jarvis e organizado em 5 camadas.

package/bin/README.md

@@ -11,7 +11,7 @@ bin/
 ├── commands/                  # Um arquivo por comando. Lógica pura, zero commander.
 │   ├── init.js, list.js, info.js, whoami.js, ...
 │   ├── docs-sync.js, docs-publish.js
-│   └── install-rtk.js, tokens.js, map.js
+│   └── install-rtk.js, tokens.js, map.js, fork.js
 └── lib/
     ├── cli/
     │   ├── program.js         # Único lugar que monta o commander — ver "Arquitetura"
@@ -25,7 +25,7 @@ bin/
     ├── tasks/
     │   └── comment.js         # Comentário no card (jira/github/gitlab) pelo cli-runner — mesmo padrão
     ├── config/                # ide-config.js (fonte de verdade de IDEs), constants.js
-    ├── core/                  # scanner.js, sync-engine.js, profile-filter.js, token-report.js
+    ├── core/                  # scanner.js, sync-engine.js (inclui o RuleResolver do overlay), profile-filter.js, token-report.js, company-profile.js (COMPANY_PROFILE e o default stark-industries)
     ├── docs/                  # Central docs: fetch/publish pelo adaptador + validação de frontmatter
     │   ├── validate-frontmatter.js  # Valida/extrai frontmatter (feature, delivery e documentos de trabalho: PRD, FRD, épico, história, tarefa, ARD, RFC, QA)
     │   ├── fetch-file.js       # openStorageFromEnv() + fetchFile() — `docs sync`/`docs fetch`/`docs publish`
@@ -49,7 +49,7 @@ bin/commands/*.js          →  lógica de negócio pura: async (flags) => {...}
 
 **Por que separar assim?** `bin/commands/*.js` nunca importa `commander` nem sabe o que é um `Command`. Cada arquivo só recebe um objeto `flags` e faz o que precisa. Isso significa:
 - Testar a lógica de um comando não exige simular argv/commander — chama a função direto com um objeto.
-- Trocar de biblioteca de CLI um dia (se um dia fizer sentido) significa reescrever só `program.js`, não os 10 arquivos de comando.
+- Trocar de biblioteca de CLI um dia (se um dia fizer sentido) significa reescrever só `program.js`, não os arquivos de `bin/commands/`.
 - `program.js` é o **mapa completo** do CLI: para saber todo comando que existe, todas as flags que cada um aceita, é o único arquivo que precisa abrir.
 
 ## O adapter: commander → formato antigo de `flags`

package/bin/commands/fork.js

@@ -0,0 +1,562 @@
+/**
+ * @fileoverview `jarvis fork {nome} [--list|--update|--delete] [--candidate]` (#199): a mecânica do
+ * overlay de empresa. Copia um artefato do core instalado para `$IDE/overlays/{COMPANY_PROFILE}/`,
+ * no mesmo caminho e com o mesmo nome, carimbado no frontmatter (`forked_from`, `forked_at`,
+ * `core_candidate`); lista o que está forkado; mostra o diff fork × core atual e recarimba
+ * (`--update`); remove o fork (`--delete`). A conversa (o que ajustar, simular, confirmar) é da
+ * skill de fork: este comando grava direto no overlay, e é o único que grava lá.
+ * @module commands/fork
+ */
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+  cpSync,
+  readdirSync,
+  rmSync,
+} from "node:fs";
+import { join, dirname, relative, sep, isAbsolute } from "node:path";
+import { resolveEnvPath } from "../lib/env-loader.js";
+import { getFrameworkRoot, getPackageInfo } from "../lib/utils/paths.js";
+import { buildIndex } from "../lib/flow-map/index.js";
+import { extractFrontmatterBlock, parseFrontmatter } from "../lib/utils/frontmatter.js";
+import { readCompanyProfile } from "../lib/core/company-profile.js";
+import { applyRuleOverlay } from "../lib/core/sync-engine.js";
+import { logger, configureFromFlags } from "../lib/utils/logger.js";
+import { RED, GREEN, YELLOW, CYAN, DIM, NC } from "../lib/utils/ui.js";
+
+/** Tipos que o overlay conhece: as pastas do core que ele espelha. */
+export const OVERLAY_TYPES = Object.freeze([
+  "workflows",
+  "skills",
+  "agents",
+  "rules",
+  "rules-on-demand",
+  "templates",
+]);
+
+/** Tipos aceitos por caminho relativo (os demais vêm por nome, pelo índice do `jarvis map`). */
+const PATH_TYPES = Object.freeze(["rules", "rules-on-demand", "templates"]);
+
+/** Tipos que a IDE carrega sozinha: o fork recopia a cópia da IDE na hora (RuleResolver). */
+const RULE_TYPES = Object.freeze(["rules", "rules-on-demand"]);
+
+const STAMP_KEYS = /^(forked_from|forked_at|core_candidate):/;
+
+/** `lstat` sem lançar: enxerga link simbólico (inclusive quebrado), que o `existsSync` não vê. */
+function lstatOrNull(path) {
+  try {
+    return lstatSync(path);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * R5 do architecture.md: nenhum nível do caminho do alvo, do próprio alvo até o overlay, pode ser
+ * link simbólico (quebrado ou não), e o primeiro nível que existe precisa resolver, por `realpath`,
+ * para dentro do overlay. Uma subpasta linkada para fora (`overlays/acme/skills` → `.claude/skills`)
+ * ou um link quebrado no lugar do destino (`eng.start.md` → `/fora.md`) não podem levar o fork a
+ * gravar ou apagar lá. O próprio `overlays/{perfil}` pode ser um link (overlay num repositório da
+ * empresa): a raiz é o `realpath` dele, e a subida para nele sem o `lstat`.
+ * @param {string} overlayDir - precisa existir
+ * @param {string} target
+ * @returns {boolean}
+ */
+export function isInsideOverlay(overlayDir, target) {
+  const root = realpathSync(overlayDir);
+  let probe = target;
+  for (;;) {
+    if (probe === overlayDir) return true;
+    const stat = lstatOrNull(probe);
+    if (stat) {
+      if (stat.isSymbolicLink()) return false;
+      const real = realpathSync(probe);
+      return real === root || real.startsWith(root + sep);
+    }
+    const parent = dirname(probe);
+    if (parent === probe) return false;
+    probe = parent;
+  }
+}
+
+/**
+ * Resolve `{nome}` para um artefato do core: workflow, skill ou agente pelo nome (índice do
+ * `jarvis map`), ou `rules/…`, `rules-on-demand/…`, `templates/…` por caminho relativo.
+ * @param {string} root - Raiz do core instalado
+ * @param {string} name
+ * @returns {{ type: string, relPath: string, isDir: boolean } | null} `relPath` com `/`
+ */
+export function resolveArtifact(root, name) {
+  if (!name || isAbsolute(name) || name.split(/[\\/]/).includes("..")) return null;
+  const { items } = buildIndex(root);
+  const item = items.get(name);
+  if (item) {
+    if (item.type === "skill") return { type: "skills", relPath: dirname(item.path), isDir: true };
+    return {
+      type: item.type === "workflow" ? "workflows" : "agents",
+      relPath: item.path,
+      isDir: false,
+    };
+  }
+  const norm = name.replace(/\\/g, "/").replace(/^\.\//, "");
+  const first = norm.split("/")[0];
+  if (PATH_TYPES.includes(first) && norm.endsWith(".md") && existsSync(join(root, norm))) {
+    return { type: first, relPath: norm, isDir: false };
+  }
+  return null;
+}
+
+/**
+ * Carimba o frontmatter com a origem do fork. Sem frontmatter (ex.: template), cria um só com o
+ * carimbo. Carimbo anterior é substituído.
+ * @param {string} content
+ * @param {{ from: string, at: string, candidate?: boolean }} stamp
+ * @returns {string}
+ */
+export function stampFrontmatter(rawContent, { from, at, candidate = false }) {
+  const content = lf(rawContent);
+  const lines = [`forked_from: ${from}`, `forked_at: ${at}`];
+  if (candidate) lines.push("core_candidate: true");
+  const block = extractFrontmatterBlock(content);
+  if (block === null) return `---\n${lines.join("\n")}\n---\n\n${content}`;
+  const kept = block
+    .split("\n")
+    .filter((l) => !STAMP_KEYS.test(l))
+    .join("\n");
+  const fenceEnd = content.indexOf("\n---", 3);
+  return `---\n${kept}\n${lines.join("\n")}${content.slice(fenceEnd)}`;
+}
+
+/**
+ * Lista o que está no overlay, e só isso (não compara com o core).
+ * @param {string} overlayDir
+ * @returns {Array<{ path: string, type: string, forkedFrom: string | null, forkedAt: string | null, candidate: boolean, unknownType: boolean }>}
+ */
+export function listOverlay(overlayDir) {
+  if (!existsSync(overlayDir)) return [];
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+      const rel = relative(overlayDir, full).split(sep).join("/");
+      const type = rel.split("/")[0];
+      // Skill: uma linha por pasta (o SKILL.md), não por arquivo de references/
+      if (type === "skills" && !rel.endsWith("/SKILL.md")) continue;
+      const fm = parseFrontmatter(lf(readFileSync(full, "utf-8")));
+      out.push({
+        path: type === "skills" ? dirname(rel) : rel,
+        type,
+        forkedFrom: fm.forked_from ?? null,
+        forkedAt: fm.forked_at ?? null,
+        candidate: fm.core_candidate === "true",
+        unknownType: !OVERLAY_TYPES.includes(type),
+      });
+    }
+  };
+  walk(overlayDir);
+  return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Linhas que, mudando no core, costumam quebrar o contrato de um fork: arquivos de sessão, chaves
+ * do ENV.md, templates lidos por outros comandos e chamadas do CLI. O `--update` só marca; quem decide é a pessoa.
+ */
+const CONTRACT_PATTERN =
+  /(\.jarvis\/sessions|\$SESSIONS_DIR|architecture\.md|plan\.md|gate-checklist|pull-request\.md|ENV\.md|[A-Z][A-Z_]{3,}=|templates\/|\bjarvis [a-z][a-z-]+)/;
+
+/** Quebras de linha do Windows viram `\n`: fork editado em CRLF não pode marcar tudo como diferente. */
+const lf = (text) => text.replace(/\r\n?/g, "\n");
+
+/** Acima disto (linhas do fork × linhas do core, depois do corte do prefixo e sufixo iguais) o LCS não roda. */
+export const DIFF_CELL_LIMIT = 25_000_000;
+
+/**
+ * Diff linha a linha (LCS) entre o fork e o core atual, sem dependência nova. O prefixo e o sufixo
+ * iguais são cortados antes do LCS; linhas iguais e as do carimbo não entram; `contract` marca
+ * mudança de contrato provável. Acima de `DIFF_CELL_LIMIT` células, não compara (`tooLarge`).
+ * @param {string} forkText
+ * @param {string} coreText
+ * @returns {{ changes: Array<{ op: "-" | "+", line: string, index: number }>, contract: boolean, tooLarge: boolean, removed?: number, added?: number }}
+ *   `-` = só no fork (`index` na linha do fork) · `+` = só no core atual (`index` na linha do core);
+ *   com `tooLarge`, `removed`/`added` são as contagens do miolo diferente e `changes` vem vazio
+ */
+export function diffAgainstCore(forkText, coreText) {
+  const a = lf(forkText).split("\n");
+  const b = lf(coreText).split("\n");
+  // Corta o prefixo e o sufixo iguais: o LCS só vê o miolo que mudou.
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+  let endA = a.length;
+  let endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+    endA--;
+    endB--;
+  }
+  const midA = a.slice(start, endA);
+  const midB = b.slice(start, endB);
+  const n = midA.length;
+  const m = midB.length;
+  if ((n + 1) * (m + 1) > DIFF_CELL_LIMIT) {
+    return { changes: [], contract: false, tooLarge: true, removed: n, added: m };
+  }
+  const diff = diffLcs(midA, midB);
+  // Os índices do miolo voltam a ser índices do arquivo inteiro.
+  return { ...diff, changes: diff.changes.map((c) => ({ ...c, index: c.index + start })) };
+}
+
+/** Título `#…` mais próximo acima de `index` (para o `--diff` dizer em que seção a mudança está). */
+function sectionBefore(lines, index) {
+  for (let k = Math.min(index, lines.length - 1); k >= 0; k--) {
+    if (/^#{1,6} /.test(lines[k])) return lines[k];
+  }
+  return null;
+}
+
+function diffLcs(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const lcs = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+  const changes = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      changes.push({ op: "-", line: a[i], index: i });
+      i++;
+    } else {
+      changes.push({ op: "+", line: b[j], index: j });
+      j++;
+    }
+  }
+  while (i < n) {
+    changes.push({ op: "-", line: a[i], index: i });
+    i++;
+  }
+  while (j < m) {
+    changes.push({ op: "+", line: b[j], index: j });
+    j++;
+  }
+  const relevant = changes.filter((c) => !STAMP_KEYS.test(c.line));
+  return {
+    changes: relevant,
+    contract: relevant.some((c) => CONTRACT_PATTERN.test(c.line)),
+    tooLarge: false,
+  };
+}
+
+/**
+ * Tabela do `--list`: Caminho | Tipo | forked_from | forked_at | Candidato. Só lista; não compara.
+ * @param {ReturnType<typeof listOverlay>} entries
+ * @returns {string[]} linhas (cabeçalho, separador e uma por fork)
+ */
+export function formatOverlayTable(entries) {
+  const rows = entries.map((e) => [
+    e.path,
+    e.unknownType ? `⚠️ tipo não resolvido (${e.type})` : e.type,
+    e.forkedFrom ?? "(sem carimbo)",
+    e.forkedAt ?? "—",
+    e.candidate ? "candidato a core" : "—",
+  ]);
+  const header = ["Caminho", "Tipo", "forked_from", "forked_at", "Candidato"];
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  const line = (cells) =>
+    cells
+      .map((c, i) => c.padEnd(widths[i]))
+      .join("  ")
+      .trimEnd();
+  return [
+    `  ${line(header)}`,
+    `  ${widths.map((w) => "-".repeat(w)).join("  ")}`,
+    ...rows.map((r) => `  ${line(r)}`),
+  ];
+}
+
+/**
+ * Lê o perfil ativo a partir do ENV.md do workspace.
+ * @returns {{ ideDir: string, profile: string, overlayDir: string, warning: string | null } | { error: string }}
+ */
+function readContext(flags) {
+  let resolved;
+  try {
+    resolved = resolveEnvPath(process.cwd(), flags);
+  } catch (err) {
+    return { error: err.message.split("\n")[0] };
+  }
+  const ideDir = dirname(resolved.path);
+  const envText = existsSync(resolved.path) ? readFileSync(resolved.path, "utf-8") : undefined;
+  const { profile, warning } = readCompanyProfile(envText);
+  return { ideDir, profile, warning, overlayDir: join(ideDir, "overlays", profile) };
+}
+
+/**
+ * `jarvis fork {nome}` / `jarvis fork --list`.
+ * @param {Record<string, unknown> & { _?: string[] }} flags
+ * @returns {Promise<number>} código de saída (também gravado em `process.exitCode`)
+ */
+export async function fork(flags = {}) {
+  configureFromFlags(flags);
+  const exit = (code) => {
+    process.exitCode = code;
+    return code;
+  };
+
+  const ctx = readContext(flags);
+  if (ctx.error) {
+    logger.error(`${RED}🚫 ${ctx.error}${NC}`);
+    logger.info(`${DIM}Rode jarvis init e depois /jarvis-init na IDE.${NC}`);
+    return exit(1);
+  }
+  if (ctx.warning) logger.info(`${YELLOW}${ctx.warning}${NC}`);
+
+  if (flags.list) {
+    const entries = listOverlay(ctx.overlayDir);
+    if (entries.length === 0) {
+      logger.info(
+        `ℹ️ Overlay "${ctx.profile}" sem forks. Use /jarvis-fork {artefato} para começar.`
+      );
+      return exit(0);
+    }
+    logger.info(`${CYAN}Overlay ${ctx.profile}: ${entries.length} fork(s)${NC}`);
+    for (const line of formatOverlayTable(entries)) logger.info(line);
+    return exit(0);
+  }
+
+  const name = flags._?.[0];
+  if (!name) {
+    logger.error(
+      `${RED}Uso: jarvis fork {nome} [--candidate] | jarvis fork {nome} --update | jarvis fork {nome} --delete | jarvis fork --list${NC}`
+    );
+    return exit(1);
+  }
+
+  const root = getFrameworkRoot();
+  const artifact = resolveArtifact(root, name) ?? resolveInOverlay(ctx.overlayDir, name);
+  if (!artifact) {
+    logger.error(
+      `${YELLOW}⚠️ "${name}" não é um artefato do core. Use /jarvis-fork --list para ver o que já está no overlay ou jarvis map para os nomes do core.${NC}`
+    );
+    return exit(1);
+  }
+
+  const src = join(root, artifact.relPath);
+  const dest = join(ctx.overlayDir, artifact.relPath);
+
+  if (flags.delete) return exit(deleteFork({ ctx, artifact, name, src, dest }));
+  if (flags.update) {
+    return exit(
+      updateFork({
+        ctx,
+        artifact,
+        name,
+        src,
+        dest,
+        candidate: flags.candidate === true,
+        showDiff: flags.diff === true,
+      })
+    );
+  }
+
+  // lstat, não existsSync: um link quebrado no lugar do destino também ocupa o caminho.
+  if (lstatOrNull(dest)) {
+    logger.error(
+      `${YELLOW}⚠️ ${artifact.relPath} já está no overlay "${ctx.profile}" (ou o caminho está ocupado por um link). Use /jarvis-fork ${name} --update para ajustar.${NC}`
+    );
+    return exit(1);
+  }
+
+  // O fork é quem cria a pasta do overlay quando ela ainda não existe (o sync também a cria).
+  mkdirSync(ctx.overlayDir, { recursive: true });
+  if (!isInsideOverlay(ctx.overlayDir, dest)) {
+    logger.error(
+      `${RED}⚠️ ${artifact.relPath} resolve para fora do overlay "${ctx.profile}" (link simbólico?); nada gravado.${NC}`
+    );
+    return exit(1);
+  }
+
+  const stamp = {
+    from: `${name}@${getPackageInfo().version}`,
+    at: new Date().toISOString().slice(0, 10),
+    candidate: Boolean(flags.candidate),
+  };
+  mkdirSync(dirname(dest), { recursive: true });
+  if (artifact.isDir) {
+    cpSync(src, dest, { recursive: true });
+    const skillMd = join(dest, "SKILL.md");
+    writeFileSync(skillMd, stampFrontmatter(readFileSync(skillMd, "utf-8"), stamp), "utf-8");
+  } else {
+    writeFileSync(dest, stampFrontmatter(readFileSync(src, "utf-8"), stamp), "utf-8");
+  }
+
+  const shownDest = relative(dirname(ctx.ideDir), dest).split(sep).join("/");
+  logger.info(`${GREEN}✓ Fork gravado:${NC} ${shownDest}`);
+  logger.info(
+    `${DIM}  forked_from: ${stamp.from} · forked_at: ${stamp.at}${stamp.candidate ? " · core_candidate: true" : ""}${NC}`
+  );
+
+  if (RULE_TYPES.includes(artifact.type)) {
+    // A IDE carrega rules/ sozinha: recopia agora, sem esperar o próximo jarvis init --upgrade
+    const result = { copied: [], skipped: [], errors: [] };
+    applyRuleOverlay(ctx.ideDir, result);
+    if (result.errors.length > 0) {
+      for (const e of result.errors) logger.error(`${RED}  ✗ ${e}${NC}`);
+      logger.error(
+        `${RED}  O fork está no overlay, mas a cópia na IDE falhou: corrija e rode jarvis init --upgrade.${NC}`
+      );
+      return exit(1);
+    }
+    logger.info(
+      `${DIM}  ${artifact.type}/ recopiada na IDE com a marcação "> Overlay: ${ctx.profile}"${NC}`
+    );
+  } else {
+    logger.info(
+      `${DIM}  Vale na próxima chamada (rule de precedência). Edite o arquivo do overlay, não o da IDE.${NC}`
+    );
+  }
+  logger.info(
+    `${DIM}  A conversa e a confirmação ficam na skill de fork; este comando grava direto.${NC}`
+  );
+  return exit(0);
+}
+
+/**
+ * Para `--update`/`--delete` de um artefato que o core deixou de ter: acha o fork pelo mesmo
+ * critério de nome, só que dentro do overlay.
+ */
+function resolveInOverlay(overlayDir, name) {
+  if (!existsSync(overlayDir)) return null;
+  const found = resolveArtifact(overlayDir, name);
+  return found ? { ...found, onlyInOverlay: true } : null;
+}
+
+function mainFile(artifact, base) {
+  return artifact.isDir ? join(base, "SKILL.md") : base;
+}
+
+/**
+ * `--update`: a conversa é da skill; aqui, o recarimbo (sem `--diff`) ou, com `--diff`, só o diff
+ * fork × core atual, agrupado pela seção `#…` mais próxima, **sem gravar nada**: ver o diff não
+ * muda o carimbo; a skill chama o `--update` sem `--diff` depois do Sim. O recarimbo não altera o
+ * conteúdo do fork, mas regrava o arquivo em LF.
+ */
+function updateFork({ ctx, artifact, name, src, dest, candidate = false, showDiff = false }) {
+  if (!existsSync(dest)) {
+    logger.error(
+      `${YELLOW}⚠️ ${name} não está no overlay "${ctx.profile}". Use /jarvis-fork ${name} para forkar.${NC}`
+    );
+    return 1;
+  }
+  // Confere o destino e, numa skill, também o SKILL.md: a pasta pode ser real e o arquivo um link
+  // para fora (o writeFileSync seguiria o link).
+  const forkPath = mainFile(artifact, dest);
+  if (!isInsideOverlay(ctx.overlayDir, dest) || !isInsideOverlay(ctx.overlayDir, forkPath)) {
+    logger.error(
+      `${RED}⚠️ ${artifact.relPath} resolve para fora do overlay "${ctx.profile}" (link simbólico?); nada alterado.${NC}`
+    );
+    return 1;
+  }
+  if (artifact.onlyInOverlay || !existsSync(src)) {
+    logger.info(
+      `${YELLOW}⚠️ O core atual não tem mais ${artifact.relPath}. O fork continua valendo; se não for mais necessário, use /jarvis-fork ${name} --delete.${NC}`
+    );
+    return 0;
+  }
+  const forkText = lf(readFileSync(forkPath, "utf-8"));
+  const version = getPackageInfo().version;
+
+  if (showDiff) {
+    const coreText = lf(readFileSync(mainFile(artifact, src), "utf-8"));
+    const diff = diffAgainstCore(forkText, coreText);
+    if (diff.tooLarge) {
+      logger.info(
+        `${YELLOW}Diff ${name}: arquivos grandes demais para comparar linha a linha (${diff.removed} linhas só do fork, ${diff.added} só do core atual, fora o trecho igual). Compare com uma ferramenta de diff.${NC}`
+      );
+    } else if (diff.changes.length === 0) {
+      logger.info(`${GREEN}✅ ${name}: o fork é igual ao core atual (v${version}).${NC}`);
+    } else {
+      logger.info(
+        `${CYAN}Diff ${name}: fork (-) × core atual v${version} (+)${diff.contract ? `  ${RED}🔴 possível mudança de contrato${NC}` : ""}${NC}`
+      );
+      const forkLines = forkText.split("\n");
+      const coreLines = coreText.split("\n");
+      let lastSection;
+      for (const c of diff.changes) {
+        const section = sectionBefore(c.op === "-" ? forkLines : coreLines, c.index);
+        if (section !== lastSection) {
+          logger.info(`${CYAN}── ${section ?? "(início do arquivo)"}${NC}`);
+          lastSection = section;
+        }
+        const color = c.op === "-" ? YELLOW : GREEN;
+        logger.info(`${color}${c.op} ${c.line}${NC}`);
+      }
+      logger.info(
+        `${DIM}  Linhas "-" são só do fork (seus ajustes ou texto antigo do core); "+" são só do core atual. O que trazer é decisão sua, na skill de fork.${NC}`
+      );
+    }
+    logger.info(
+      `${DIM}  Nada gravado: ver o diff não muda o carimbo. Para recarimbar, rode --update sem --diff.${NC}`
+    );
+    return 0;
+  }
+
+  logger.info(
+    `${DIM}  Sem comparação com o core (use --diff para ver o que o core atual tem de diferente).${NC}`
+  );
+  const current = parseFrontmatter(forkText);
+  const stamped = stampFrontmatter(forkText, {
+    from: `${name}@${version}`,
+    at: current.forked_at ?? new Date().toISOString().slice(0, 10),
+    candidate: candidate || current.core_candidate === "true",
+  });
+  // Regrava mesmo sem mudança de carimbo quando o arquivo estava em CRLF: o fork fica em LF.
+  if (stamped !== readFileSync(forkPath, "utf-8")) writeFileSync(forkPath, stamped, "utf-8");
+  logger.info(`${DIM}  forked_from: ${name}@${version} (arquivo regravado em LF)${NC}`);
+  return 0;
+}
+
+/**
+ * `--delete`: remove o fork do overlay; rule e rule-on-demand voltam ao core na IDE
+ * (sem marcação). A pergunta "Remover o fork e voltar ao core?" é da skill.
+ */
+function deleteFork({ ctx, artifact, name, src, dest }) {
+  if (!existsSync(dest)) {
+    logger.error(`${YELLOW}⚠️ ${name} não está no overlay "${ctx.profile}". Nada a remover.${NC}`);
+    return 1;
+  }
+  if (!isInsideOverlay(ctx.overlayDir, dest)) {
+    logger.error(
+      `${RED}⚠️ ${artifact.relPath} resolve para fora do overlay "${ctx.profile}" (link simbólico?); nada removido.${NC}`
+    );
+    return 1;
+  }
+  rmSync(dest, { recursive: true, force: true });
+  logger.info(`${GREEN}✓ Fork removido:${NC} overlays/${ctx.profile}/${artifact.relPath}`);
+  if (RULE_TYPES.includes(artifact.type)) {
+    const ideCopy = join(ctx.ideDir, artifact.relPath);
+    if (existsSync(src)) {
+      mkdirSync(dirname(ideCopy), { recursive: true });
+      cpSync(src, ideCopy);
+      logger.info(`${DIM}  ${artifact.relPath} voltou à versão do core na IDE${NC}`);
+    } else if (existsSync(ideCopy)) {
+      rmSync(ideCopy, { force: true });
+      logger.info(`${DIM}  ${artifact.relPath} removida da IDE: o core atual não a tem${NC}`);
+    }
+  }
+  return 0;
+}