jarvis-ai-framework 3.2.0 → 4.0.0

package/agents/product/prod.discovery-interviewer.md

@@ -75,7 +75,7 @@ Não use quando já existe uma spec (use `/prod.spec.clarify`) ou quando o escop
 As skills são apoio, nunca a fonte da decisão. A busca em `$PROD_DOCS` não é uma skill: é feita sempre, antes de perguntar.
 
 ### jarvis-docs-central
-Para buscar documentação do produto no repositório central, quando `CENTRAL_DOCS_REPO` estiver configurado:
+Para buscar documentação do produto no Central docs, quando `CENTRAL_DOCS_STORAGE` estiver configurado:
 - Arquivo: `$IDE/skills/jarvis-docs-central/SKILL.md`
 - Confiança: sempre
 

package/bin/README.md

@@ -17,17 +17,17 @@ bin/
     │   ├── program.js         # Único lugar que monta o commander — ver "Arquitetura"
     │   └── shared-options.js  # .option() repetidos entre comandos (--ide, --quiet, etc.)
     ├── vcs/                   # Adapters de Git host (GitLab/GitHub/Bitbucket)
-    │   ├── api.js             # Lógica HTTP real (createIssue, createMergeRequest, fetchRawFile)
-    │   ├── create-merge.js, create-issue.js, fetch-raw.js   # função exportada + CLI direto (ver abaixo)
+    │   ├── api.js             # Lógica HTTP real (createIssue, createMergeRequest)
+    │   ├── create-merge.js, create-issue.js   # função exportada + CLI direto (ver abaixo)
     ├── tasks/
     │   └── comment.js         # Adapter de task manager (jira/linear/github/asana) — 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
-    ├── docs/                  # central-docs: fetch/publish + validação de frontmatter
-    │   ├── validate-frontmatter.js  # Valida/extrai frontmatter de PRD/FRD/ARD/RFC
-    │   ├── redis-cache.js      # Cache best-effort via `redis-cli` (get/setex/del)
-    │   ├── fetch-file.js       # fetchFile() — usado por `docs sync`/`docs fetch` e por publish-file.js
-    │   └── publish-file.js     # publishFile() — usado por `docs publish`
+    ├── docs/                  # Central docs: fetch/publish pelo adaptador + validação de frontmatter
+    │   ├── validate-frontmatter.js  # Valida/extrai frontmatter (PRD, FRD, épico, história, tarefa, ARD, RFC)
+    │   ├── fetch-file.js       # openStorageFromEnv() + fetchFile() — `docs sync`/`docs fetch`/`docs publish`
+    │   ├── publish-file.js     # tipos, resolveDestPath() e publishFile() — `docs publish`
+    │   └── storage/            # adaptadores (CENTRAL_DOCS_STORAGE): index.js (fábrica), filesystem.js (pasta + git), build-index.js
     ├── utils/                 # logger.js, ui.js, paths.js, frontmatter.js, git-parser.js, npmrc-parser.js
     ├── flow-map/              # `jarvis map` — grafo de chamadas entre workflows/skills/agents
     ├── auth/                  # session.js (auth.json legado, hoje só `jarvis logout` o lê)
@@ -77,22 +77,22 @@ O parser manual antigo nunca validava nada: qualquer `--flag` era aceito e ignor
 
 ## Argumentos: `[opcional]`, não `<obrigatório>` — de propósito
 
-Note que `info`, `vcs fetch-raw` e `tasks comment` declaram seus positionals como **opcionais** (`[target]`, `[file-path]`) mesmo sendo, na prática, obrigatórios para o comando funcionar. Isso é deliberado: se o commander validar "argumento obrigatório ausente" sozinho, ele intercepta **antes** da função rodar — e cada uma dessas funções já tem sua própria validação com mensagem de uso customizada e mais específica (`info.js`: `"❌ Uso incorreto\nUso: jarvis info <type/name>\nExemplo: ..."`). Deixar o positional opcional no commander e a validação dentro da função preserva essa mensagem.
+Note que `info` e `tasks comment` declaram seus positionals como **opcionais** (`[target]`, `[card-key]`) mesmo sendo, na prática, obrigatórios para o comando funcionar. Isso é deliberado: se o commander validar "argumento obrigatório ausente" sozinho, ele intercepta **antes** da função rodar — e cada uma dessas funções já tem sua própria validação com mensagem de uso customizada e mais específica (`info.js`: `"❌ Uso incorreto\nUso: jarvis info <type/name>\nExemplo: ..."`). Deixar o positional opcional no commander e a validação dentro da função preserva essa mensagem.
 
-**A mesma regra vale para `--flag` que já tem validação própria.** Nenhum comando aqui usa `.requiredOption()` ou `.choices()` do commander, mesmo quando faria sentido à primeira vista (ex: `--tipo` em `docs publish` só aceita `prd|frd|ard|rfc|swagger|qa-report`). `docsPublish.js` já valida isso e mostra um bloco de exemplos de uso bem mais rico que o que o commander mostraria. Usar `.choices()` ali faria o commander interceptar o valor errado com uma mensagem genérica, perdendo esse texto. **Ao adicionar uma opção nova**: se a função já vai validar o valor por dentro, deixe o commander permissivo (`.option()` simples) e confie na validação interna. Se não há validação nenhuma hoje, `.choices()`/`.argParser()` são bons lugares para adicionar uma — não há essa perda a proteger.
+**A mesma regra vale para `--flag` que já tem validação própria.** Nenhum comando aqui usa `.requiredOption()` ou `.choices()` do commander, mesmo quando faria sentido à primeira vista (ex: `--tipo` em `docs publish` só aceita os tipos de `VALID_TYPES`). `docsPublish.js` já valida isso e mostra um bloco de exemplos de uso bem mais rico que o que o commander mostraria. Usar `.choices()` ali faria o commander interceptar o valor errado com uma mensagem genérica, perdendo esse texto. **Ao adicionar uma opção nova**: se a função já vai validar o valor por dentro, deixe o commander permissivo (`.option()` simples) e confie na validação interna. Se não há validação nenhuma hoje, `.choices()`/`.argParser()` são bons lugares para adicionar uma — não há essa perda a proteger.
 
 ## `program.command()` vs `program.addCommand()`
 
 Este código usa `.command(nome)` (que cria e já anexa o subcomando) em todo lugar — não `.addCommand(instanciaDeCommand)`. São equivalentes; `.addCommand()` só compensa quando o `Command` é montado em outro módulo e precisa ser importado antes de anexar. Como tudo mora em `program.js`, não há motivo para o nível extra de indireção.
 
-## Os 4 "scripts standalone" (`vcs/*.js`, `tasks/comment.js`): dupla forma
+## Os 3 "scripts standalone" (`vcs/*.js`, `tasks/comment.js`): dupla forma
 
-`create-merge.js`, `create-issue.js`, `fetch-raw.js` e `comment.js` são chamados de duas formas:
+`create-merge.js`, `create-issue.js` e `comment.js` são chamados de duas formas:
 
 1. **Como subcomando do CLI**: `jarvis vcs create-merge --source ... --target ...` (via `program.js`)
 2. **Direto, por skills/workflows que ainda shell-am pra eles**: `node bin/lib/vcs/create-merge.js --source ...`
 
-Cada um dos 4 arquivos segue o mesmo padrão: exporta uma função (`runCreateMerge`, `runCreateIssue`, `runFetchRaw`, `runComment`) com a lógica, e termina com um guard que só lê `process.argv` quando o arquivo é executado diretamente:
+Cada um dos 3 arquivos segue o mesmo padrão: exporta uma função (`runCreateMerge`, `runCreateIssue`, `runComment`) com a lógica, e termina com um guard que só lê `process.argv` quando o arquivo é executado diretamente:
 
 ```js
 // Compatibilidade: continua funcionando como `node bin/lib/vcs/create-merge.js --source ...`
@@ -131,9 +131,9 @@ Os 3 arquivos mais críticos sem cobertura até pouco tempo atrás (`env-loader.
 - **`env-loader.js`** (e `flow-map.test.js`, mais antigo): `mkdtempSync(join(tmpdir(), "jarvis-..."))` monta um workspace fake com `.{ide}/ENV.md`, roda a função contra ele, `rmSync` no `finally`.
 - **`sync-engine.js`**: `getFrameworkRoot()` (`utils/paths.js`) já tem um escape hatch — `process.env.JARVIS_ROOT`, se definido e existir, vence sobre o framework real. O teste aponta `JARVIS_ROOT` para um fixture mínimo (`agents/`, `skills/`, etc. com 1 arquivo cada) em vez de sincronizar o framework inteiro.
 - **`vcs/api.js`**: usa `mock.method(globalThis, "fetch", ...)` do `node:test` pra controlar a resposta por vendor, sem mockar o módulo nem tocar rede real. **Atenção**: toda função de rede chama `getVcsToken()` antes do fetch — fixe `GITLAB_TOKEN`/`GITHUB_TOKEN`/`BITBUCKET_TOKEN` via env var no teste (ver `withEnv` em `vcs-api.test.js`), senão o resultado depende do que a máquina que roda o teste tiver em `.npmrc`/`gh auth`.
-- **`docs/fetch-file.js`/`docs/publish-file.js`**: mesmo mock de `fetch`. `redis-cli` (chamado por `docs/redis-cache.js`) **não dá pra mockar** — é um módulo nativo (`node:child_process`) não configurável, `mock.method` lança `TypeError: Cannot redefine property`. Como pode haver um `redis-cli` de verdade instalado (com ou sem servidor acessível) na máquina que roda o teste, cada teste usa uma chave de cache única (`docs:${randomUUID()}...`) em vez de mockar o cache — garante cache-miss determinístico sem depender do estado de nenhum Redis real.
+- **`docs/` (Central docs)**: tudo em pasta temporária (`mkdtempSync`). A camada git do adaptador `filesystem` usa um repositório `git init --bare` local como `origin` (sem rede), e o `createMergeRequest` é injetado pelo parâmetro `deps` de `getStorage` (ver `docs-storage.test.js`).
 
-**Armadilha com `async`**: o helper `withEnv(vars, fn)` (repetido nos 3 arquivos acima) precisa de `return **await** fn()`, não `return fn()`, dentro do `try`. Sem o `await`, o `finally` que restaura a env var roda assim que `fn()` retorna uma Promise pendente — ou seja, **antes** da função terminar. Isso só não quebra quando a leitura da env var acontece antes do primeiro `await` de `fn` (ex: `fetchRawFile` lê o token antes do seu próprio `fetch`); quebra silenciosamente em qualquer função com mais de um `await` no meio do caminho (ex: `publishFile`, que busca o `index.md` antes de chegar no commit, que é onde o token é lido).
+**Armadilha com `async`**: o helper `withEnv(vars, fn)` (em `vcs-api.test.js`) precisa de `return **await** fn()`, não `return fn()`, dentro do `try`. Sem o `await`, o `finally` que restaura a env var roda assim que `fn()` retorna uma Promise pendente — ou seja, **antes** da função terminar. Isso só não quebra quando a leitura da env var acontece antes do primeiro `await` de `fn` (ex: `createIssue` lê o token antes do seu próprio `fetch`); quebra silenciosamente em qualquer função com mais de um `await` antes de ler a variável.
 
 Ao escrever um teste novo para um arquivo que toca `fs`/rede, prefira um desses padrões a mockar o módulo inteiro ou refatorar pra injeção de dependência — nenhum dos arquivos acima precisou mudar uma linha de lógica de produção para ganhar teste.
 

package/bin/commands/docs-publish.js

@@ -1,148 +1,106 @@
-import { loadEnv, resolveEnvPath } from "../lib/env-loader.js";
 import { existsSync } from "node:fs";
-import { publishFile } from "../lib/docs/publish-file.js";
+import { openStorageFromEnv } from "../lib/docs/fetch-file.js";
+import { publishFile, VALID_TYPES } from "../lib/docs/publish-file.js";
 import { logger, configureFromFlags } from "../lib/utils/logger.js";
 
 /**
- * Publica documento no central-docs via GitLab API (branch + MR)
+ * Publica um documento no Central docs pelo adaptador configurado.
+ * Sem `.git` na pasta: copia e regenera o índice. Com `.git`: branch, commit, push e PR.
  *
  * @param {Object} flags - Flags do comando
  * @param {string} flags.file - Caminho do arquivo local
- * @param {string} flags.tipo - Tipo do documento (prd|frd|ard|rfc)
- * @param {string} flags.feature - Slug da feature (kebab-case)
- * @param {string} flags.squad - Squad (opcional, override do ENV.md)
- * @param {string} flags.workspace - Workspace (opcional, override do ENV.md)
+ * @param {string} flags.tipo - Tipo do documento (ver VALID_TYPES)
+ * @param {string} [flags.produto] - Pasta do produto (padrão: WORKSPACE do ENV.md)
+ * @param {string} [flags.feature] - Slug, só se o nome do arquivo fugir do padrão {tipo}-{id}-{nome}
+ * @param {string} [flags.squad] - Override do SQUAD do ENV.md
+ * @param {string} [flags.workspace] - Override do WORKSPACE (padrão do --produto)
  * @param {string} flags.envFile - Path customizado do ENV.md
  */
 export async function docsPublish(flags = {}) {
   configureFromFlags(flags);
 
-  const { file, tipo, feature, squad: squadOverride, workspace: workspaceOverride } = flags;
+  const {
+    file,
+    tipo,
+    feature,
+    produto,
+    squad: squadOverride,
+    workspace: workspaceOverride,
+  } = flags;
 
-  // Validar parâmetros obrigatórios
-  if (!file || !tipo || !feature) {
+  if (!file || !tipo) {
     logger.error("❌ Parâmetros obrigatórios faltando\n");
     logger.error(
-      "Uso: jarvis docs publish --file <path> --tipo <prd|frd|ard|rfc|swagger|qa-report> --feature <slug> [--squad <squad>] [--workspace <workspace>]\n"
+      `Uso: jarvis docs publish --file <path> --tipo <${VALID_TYPES.join("|")}> [--produto <produto>] [--feature <slug>] [--squad <squad>]\n`
     );
-    logger.error("Exemplo:");
-    logger.error("  jarvis docs publish \\");
-    logger.error("    --file ./docs/engineering/ard-api-wallet.md \\");
-    logger.error("    --tipo ard \\");
-    logger.error("    --feature api-wallet-auth-jwt");
+    logger.error("Exemplo (o nome do arquivo já segue {tipo}-{id}-{nome}):");
+    logger.error("  jarvis docs publish --file ./docs/product/prd-001-checkout.md --tipo prd");
     logger.error("");
-    logger.error("  # Publicar Swagger/OpenAPI:");
-    logger.error("  jarvis docs publish \\");
-    logger.error("    --file ./docs/engineering/swagger/api-wallet.yaml \\");
-    logger.error("    --tipo swagger \\");
-    logger.error("    --feature api-wallet");
-    logger.error("");
-    logger.error("  # Com override de squad/workspace:");
-    logger.error("  jarvis docs publish \\");
-    logger.error("    --file ./docs/engineering/ard-api-wallet.md \\");
-    logger.error("    --tipo ard \\");
-    logger.error("    --feature api-wallet-auth-jwt \\");
-    logger.error("    --squad core \\");
-    logger.error("    --workspace meu-workspace");
+    logger.error("  # Arquivo fora do padrão de nome:");
+    logger.error(
+      "  jarvis docs publish --file ./docs/engineering/swagger/api.yaml --tipo swagger --feature api-wallet"
+    );
     process.exit(1);
   }
 
-  // Validar tipo
-  const validTypes = ["prd", "frd", "ard", "rfc", "swagger", "qa-report"];
-  if (!validTypes.includes(tipo)) {
+  if (!VALID_TYPES.includes(tipo)) {
     logger.error(`❌ Tipo inválido: ${tipo}`);
-    logger.error(`Tipos válidos: ${validTypes.join(", ")}`);
+    logger.error(`Tipos válidos: ${VALID_TYPES.join(", ")}`);
     process.exit(1);
   }
 
-  // Validar se arquivo existe
   if (!existsSync(file)) {
     logger.error(`❌ Arquivo não encontrado: ${file}`);
     process.exit(1);
   }
 
-  const cwd = process.cwd();
-
-  // Resolver path do ENV.md (suporta --ide e --env-file)
-  let envPath;
-  try {
-    const resolved = resolveEnvPath(cwd, flags);
-    envPath = resolved.path;
-  } catch (error) {
-    logger.error("❌ Erro ao resolver ENV.md:", error.message);
-    process.exit(1);
-  }
-
-  // Carregar ENV.md
   let env;
+  let storage;
   try {
-    env = loadEnv(cwd, envPath);
+    ({ env, storage } = openStorageFromEnv(flags));
   } catch (error) {
-    logger.error("❌ Erro ao carregar ENV.md:", error.message);
+    logger.error("❌ Central docs:", error.message);
     process.exit(1);
   }
 
-  // Verificar se central-docs está configurado
-  if (!env.CENTRAL_DOCS_REPO) {
-    logger.error("❌ CENTRAL_DOCS_REPO não configurado no ENV.md");
-    logger.error("\nConfigure a URL do repositório central:");
-    logger.error("  CENTRAL_DOCS_REPO=https://gitlab.com/org/central-docs.git");
+  if (!storage) {
+    logger.error("❌ Central docs desligado (CENTRAL_DOCS_STORAGE vazio no ENV.md).");
+    logger.error("   Configure-o com o /jarvis-init.");
     process.exit(1);
   }
 
-  // Usar override de squad/workspace se fornecido, senão usar do ENV.md
   const squad = squadOverride || env.SQUAD;
-  const workspace = workspaceOverride || env.WORKSPACE;
+  const product = produto || workspaceOverride || env.WORKSPACE;
 
-  if (!squad || !workspace) {
+  if (!squad || !product) {
     logger.error("❌ SQUAD ou WORKSPACE não definidos");
-    logger.error("\nOpções:");
-    logger.error("  1. Definir no ENV.md:");
-    logger.error("     SQUAD=core");
-    logger.error("     WORKSPACE=meu-workspace");
-    logger.error("");
-    logger.error("  2. Passar via flags:");
-    logger.error("     --squad core --workspace meu-workspace");
+    logger.error("   Defina no ENV.md ou passe --squad <squad> --produto <produto>");
     process.exit(1);
   }
 
-  logger.info(`📤 Publicando ${tipo.toUpperCase()} ${feature}...\n`);
+  logger.info(`📤 Publicando ${tipo.toUpperCase()} (${file})...\n`);
 
   try {
-    await publishFile({
-      localFile: file,
-      tipo,
-      feature,
-      squad,
-      workspace,
-      repo: env.CENTRAL_DOCS_REPO,
-      targetBranch: env.CENTRAL_DOCS_TARGET_BRANCH || "dev",
-      cacheTtl: env.CENTRAL_DOCS_CACHE_TTL || "3600",
-    });
+    await publishFile({ storage, localFile: file, tipo, squad, produto: product, feature });
+    logger.info("");
+    logger.info("✅ Publicação concluída!");
   } catch (error) {
     logger.error("\n❌ Erro ao publicar documento\n");
     logger.error(error.message);
 
-    // Dicas de troubleshooting
-    logger.error("\n💡 Troubleshooting:\n");
-
-    if (error.message.includes("Token GitLab")) {
-      logger.error("1. Configure o token GitLab no .npmrc:");
-      logger.error("   //gitlab.com/api/v4/packages/npm/:_authToken=seu-token\n");
-    }
-
     if (error.message.includes("Campos obrigatórios")) {
-      logger.error("2. Verifique o frontmatter do documento:");
-      logger.error(`   Tipo ${tipo} requer campos específicos no YAML\n`);
+      logger.error(
+        `\n💡 Verifique o frontmatter do documento: o tipo ${tipo} exige campos específicos.`
+      );
     }
-
-    if (error.message.includes("401") || error.message.includes("403")) {
-      logger.error("4. Verifique permissões no GitLab:");
-      logger.error("   Token precisa de scopes: api, read_api, write_repository\n");
+    if (storage.isGit) {
+      logger.error(
+        "\n💡 Central docs com git: confira se a pasta está limpa (git status), se você tem permissão de push"
+      );
+      logger.error(
+        "   e se o token do vendor está configurado (GitLab .npmrc, GitHub gh auth, BITBUCKET_TOKEN)."
+      );
     }
-
-    logger.error("Para mais detalhes, execute com --verbose");
-
     process.exit(1);
   }
 }

package/bin/commands/docs-sync.js

@@ -1,10 +1,11 @@
-import { loadEnv, resolveEnvPath } from "../lib/env-loader.js";
-import { fetchFile } from "../lib/docs/fetch-file.js";
+import { openStorageFromEnv } from "../lib/docs/fetch-file.js";
 import { logger, configureFromFlags } from "../lib/utils/logger.js";
 
+const COUNTED_TYPES = ["prd", "frd", "feat", "epic", "story", "task", "ard", "rfc"];
+
 /**
- * Sincroniza documentação do central-docs
- * Executado automaticamente em /warm-up
+ * Sincroniza a documentação do Central docs (lê `{SQUAD}/index.md` pelo adaptador).
+ * Executado automaticamente em /warm-up.
  *
  * @param {Object} flags - Flags do comando
  * @param {boolean} flags.silent - Modo silencioso (nem erros aparecem)
@@ -15,87 +16,53 @@ import { logger, configureFromFlags } from "../lib/utils/logger.js";
 export async function docsSync(flags = {}) {
   configureFromFlags(flags);
 
-  const cwd = process.cwd();
-
-  // Resolver path do ENV.md (suporta --ide e --env-file)
-  let envPath;
-  try {
-    const resolved = resolveEnvPath(cwd, flags);
-    envPath = resolved.path;
-  } catch (error) {
-    logger.error("❌ Erro ao resolver ENV.md:", error.message);
-    process.exit(1);
-  }
-
-  // Carregar ENV.md
   let env;
+  let storage;
   try {
-    env = loadEnv(cwd, envPath);
+    ({ env, storage } = openStorageFromEnv(flags));
   } catch (error) {
-    logger.error("❌ Erro ao carregar ENV.md:", error.message);
+    logger.error("❌ Central docs:", error.message);
     process.exit(1);
   }
 
-  // Verificar se central-docs está configurado
-  if (!env.CENTRAL_DOCS_REPO) {
-    logger.info("ℹ️  Central docs não configurado (CENTRAL_DOCS_REPO vazio)");
+  if (!storage) {
+    logger.info("ℹ️  Central docs desligado (CENTRAL_DOCS_STORAGE vazio)");
     return;
   }
 
-  const { SQUAD, WORKSPACE, CENTRAL_DOCS_REF = "main" } = env;
-
-  if (!SQUAD || !WORKSPACE) {
-    logger.error("❌ SQUAD ou WORKSPACE não definidos no ENV.md");
+  const { SQUAD } = env;
+  if (!SQUAD) {
+    logger.error("❌ SQUAD não definido no ENV.md");
     process.exit(1);
   }
 
-  logger.info(`🔄 Sincronizando docs do squad ${SQUAD}...`);
-
-  // Buscar index.md do squad
-  const indexPath = `${SQUAD}/index.md`;
+  logger.info(
+    `🔄 Sincronizando docs do squad ${SQUAD} (${storage.kind}${storage.isGit ? " + git" : ""})...`
+  );
 
   try {
-    const content = await fetchFile(indexPath, CENTRAL_DOCS_REF, {
-      repo: env.CENTRAL_DOCS_REPO,
-      cacheTtl: env.CENTRAL_DOCS_CACHE_TTL || "3600",
-    });
-
+    const content = await storage.fetch(`${SQUAD}/index.md`);
     logger.info("✅ Docs sincronizados");
 
-    if (content) {
-      logger.debug("\n📄 Conteúdo do index.md:\n");
-      logger.debug(content);
-    }
+    logger.debug("\n📄 Conteúdo do index.md:\n");
+    logger.debug(content);
 
-    // Parsear index.md para contar documentos
-    if (content) {
-      const prdCount = (content.match(/\[prd-.*\.md\]/g) || []).length;
-      const frdCount = (content.match(/\[frd-.*\.md\]/g) || []).length;
-      const ardCount = (content.match(/\[ard-.*\.md\]/g) || []).length;
-      const rfcCount = (content.match(/\[rfc-.*\.md\]/g) || []).length;
+    const counts = COUNTED_TYPES.map((tipo) => [
+      tipo,
+      (content.match(new RegExp(`\\[${tipo}-[^\\]]*\\]`, "g")) || []).length,
+    ]).filter(([, n]) => n > 0);
+    const total = counts.reduce((sum, [, n]) => sum + n, 0);
 
-      const total = prdCount + frdCount + ardCount + rfcCount;
-
-      if (total > 0) {
-        logger.info(`📊 ${total} documentos disponíveis:`);
-        if (prdCount > 0) logger.info(`   - ${prdCount} PRD(s)`);
-        if (frdCount > 0) logger.info(`   - ${frdCount} FRD(s)`);
-        if (ardCount > 0) logger.info(`   - ${ardCount} ARD(s)`);
-        if (rfcCount > 0) logger.info(`   - ${rfcCount} RFC(s)`);
-      }
+    if (total > 0) {
+      logger.info(`📊 ${total} documentos disponíveis:`);
+      for (const [tipo, n] of counts) logger.info(`   - ${n} ${tipo.toUpperCase()}(s)`);
     }
   } catch (error) {
     logger.error("❌ Erro ao sincronizar docs:", error.message);
-
-    // Dicas de troubleshooting
-    if (error.message.includes("Token GitLab")) {
-      logger.error("\n💡 Configure o token GitLab no .npmrc:");
-      logger.error("   //gitlab.com/api/v4/packages/npm/:_authToken=seu-token");
-    } else if (error.message.includes("não encontrado")) {
-      logger.error("\n💡 Verifique se o squad existe no central-docs:");
-      logger.error(`   ${SQUAD}/index.md`);
+    if (error.code === 404) {
+      logger.error("\n💡 O squad ainda não tem índice no Central docs:");
+      logger.error(`   ${SQUAD}/index.md (é criado na primeira publicação: jarvis docs publish)`);
     }
-
     process.exit(1);
   }
 }

package/bin/lib/cli/program.js

@@ -28,7 +28,6 @@ import { tokens } from "../../commands/tokens.js";
 import { map } from "../../commands/map.js";
 import { runCreateMerge } from "../vcs/create-merge.js";
 import { runCreateIssue } from "../vcs/create-issue.js";
-import { runFetchRaw } from "../vcs/fetch-raw.js";
 import { runComment } from "../tasks/comment.js";
 import { fetchFile } from "../docs/fetch-file.js";
 import { formatIDEsList } from "../config/ide-config.js";
@@ -112,33 +111,38 @@ export function buildProgram() {
   const docs = cmd(program, "docs").description("Sincronizar ou publicar documentação");
 
   const docsSyncCmd = cmd(docs, "sync").description(
-    "Sincronizar docs do central-docs (usado por /warm-up)"
+    "Sincronizar docs do Central docs pelo adaptador de CENTRAL_DOCS_STORAGE (usado por /warm-up)"
   );
   withEnvOptions(withLogOptions(docsSyncCmd)).action((options) => docsSync(toLegacyFlags(options)));
 
-  cmd(docs, "fetch")
+  const docsFetchCmd = cmd(docs, "fetch")
     .description(
-      "Buscar um arquivo do central-docs, com cache Redis best-effort (lê CENTRAL_DOCS_REPO do ambiente)"
+      "Buscar um arquivo do Central docs pelo adaptador de CENTRAL_DOCS_STORAGE (com git: pull antes de ler)"
     )
-    .argument("<file-path>", "Path do arquivo dentro do repo central-docs")
-    .argument("[ref]", "Branch/ref", "main")
-    .action(async (filePath, ref) => {
-      try {
-        const content = await fetchFile(filePath, ref);
-        process.stdout.write(content);
-      } catch (error) {
-        console.error(error.message);
-        process.exit(error.code === 404 ? 2 : 1);
-      }
-    });
+    .argument("<file-path>", "Caminho do arquivo dentro do Central docs (ex: CORE/index.md)");
+  withEnvOptions(docsFetchCmd).action(async (filePath, options) => {
+    try {
+      const content = await fetchFile(filePath, { flags: toLegacyFlags(options) });
+      process.stdout.write(content);
+    } catch (error) {
+      console.error(error.message);
+      process.exit(error.code === 404 ? 2 : 1);
+    }
+  });
 
   const docsPublishCmd = cmd(docs, "publish")
-    .description("Publicar documento no central-docs (branch + MR/PR)")
+    .description(
+      "Publicar documento no Central docs (pasta: copia e regenera o índice; com git: branch + PR)"
+    )
     .option("--file <path>", "Caminho do arquivo local")
-    .option("--tipo <tipo>", "prd|frd|ard|rfc|swagger|qa-report")
-    .option("--feature <slug>", "Slug da feature (kebab-case)")
+    .option("--tipo <tipo>", "prd|frd|feat|epic|story|task|ard|rfc|swagger|qa-report")
+    .option("--produto <produto>", "Pasta do produto no Central docs (padrão: WORKSPACE do ENV.md)")
+    .option("--feature <slug>", "Só se o nome do arquivo fugir do padrão {tipo}-{id}-{nome}")
     .option("--squad <squad>", "Override do SQUAD do ENV.md")
-    .option("--workspace <workspace>", "Override do WORKSPACE do ENV.md");
+    .option(
+      "--workspace <workspace>",
+      "Override do WORKSPACE do ENV.md (mesmo efeito de --produto)"
+    );
   withEnvOptions(withLogOptions(docsPublishCmd)).action((options) =>
     docsPublish(toLegacyFlags(options))
   );
@@ -201,12 +205,6 @@ export function buildProgram() {
       runCreateIssue({ repo: options.repo, title: options.title, bodyFile: options.bodyFile })
     );
 
-  cmd(vcs, "fetch-raw")
-    .description("Buscar o conteúdo bruto de um arquivo no central-docs (lê CENTRAL_DOCS_REPO)")
-    .argument("[file-path]")
-    .argument("[ref]", "Branch/ref", "main")
-    .action((filePath, ref) => runFetchRaw(filePath, ref));
-
   const tasks = cmd(program, "tasks").description("Adapters de task manager");
 
   cmd(tasks, "comment")

package/bin/lib/docs/fetch-file.js

@@ -1,39 +1,42 @@
 /**
- * @fileoverview Busca um arquivo do central-docs (GitLab/GitHub/Bitbucket), com
- * cache Redis best-effort. Substitui `fetch-file.sh` (removido) — mesmo
- * comportamento, sem subprocess: chama `fetchRawFile` de `vcs/api.js` direto.
+ * @fileoverview Leitura do Central docs pelo adaptador configurado
+ * (`CENTRAL_DOCS_STORAGE`), venha o conteúdo de onde vier.
  * @module docs/fetch-file
  */
 
-import { fetchRawFile } from "../vcs/api.js";
-import { redisGet, redisSetex } from "./redis-cache.js";
+import { loadEnv, resolveEnvPath } from "../env-loader.js";
+import { getStorage } from "./storage/index.js";
 
 /**
- * @param {string} filePath - Path do arquivo dentro do repo central-docs
- * @param {string} [ref] - Branch/ref (padrão: "main")
+ * Carrega o ENV.md e devolve o adaptador do Central docs.
+ * @param {Object} [flags] - `envFile`/`ide` (mesmas opções dos outros comandos)
  * @param {Object} [opts]
- * @param {string} [opts.repo] - CENTRAL_DOCS_REPO (padrão: `process.env.CENTRAL_DOCS_REPO`)
- * @param {string|number} [opts.cacheTtl] - TTL do cache em segundos (padrão: `process.env.CENTRAL_DOCS_CACHE_TTL` ou 3600)
- * @returns {Promise<string>} conteúdo do arquivo
- * @throws {Error} sem `filePath`, sem `repo`, ou erro do adapter (404/401/403 — ver `fetchRawFile`)
+ * @param {string} [opts.cwd]
+ * @param {Object} [opts.deps] - Dependências injetáveis do adaptador (testes)
+ * @returns {{ env: Record<string, string>, root: string, storage: Object|null }}
  */
-export async function fetchFile(filePath, ref = "main", opts = {}) {
+export function openStorageFromEnv(flags = {}, { cwd = process.cwd(), deps } = {}) {
+  const { path, root } = resolveEnvPath(cwd, flags);
+  const env = loadEnv(cwd, path);
+  return { env, root, storage: getStorage(env, { root, deps }) };
+}
+
+/**
+ * Lê um arquivo do Central docs.
+ * @param {string} filePath - Caminho dentro do Central docs (ex: `CORE/index.md`)
+ * @param {Object} [opts]
+ * @param {Object} [opts.storage] - Adaptador já aberto; sem ele, abre pelo ENV.md
+ * @param {Object} [opts.flags]
+ * @returns {Promise<string>}
+ * @throws {Error} sem `filePath`, Central docs desligado, ou `code = 404`
+ */
+export async function fetchFile(filePath, opts = {}) {
   if (!filePath) {
     throw new Error("fetchFile: file-path é obrigatório");
   }
-
-  const repo = opts.repo ?? process.env.CENTRAL_DOCS_REPO;
-  if (!repo) {
-    throw new Error("CENTRAL_DOCS_REPO não definido no ENV.md");
+  const storage = opts.storage ?? openStorageFromEnv(opts.flags).storage;
+  if (!storage) {
+    throw new Error("Central docs desligado (CENTRAL_DOCS_STORAGE vazio no ENV.md).");
   }
-
-  const cacheKey = `docs:${filePath}:${ref}`;
-  const cached = redisGet(cacheKey);
-  if (cached) return cached;
-
-  const content = await fetchRawFile(repo, filePath, ref);
-
-  redisSetex(cacheKey, opts.cacheTtl ?? process.env.CENTRAL_DOCS_CACHE_TTL ?? "3600", content);
-
-  return content;
+  return storage.fetch(filePath);
 }