jarvis-ai-framework 3.2.0 → 5.0.0

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

@@ -0,0 +1,81 @@
+---
+name: eng.docs-consolidator.agent
+description: >
+  Especialista em organizar documentação para dois públicos, humanos e IAs. Consolida o que uma
+  entrega de fato implementou (documentos de trabalho, architecture.md, plan.md, diff e commits) em
+  documentos completos e autossuficientes para o Central docs: um por funcionalidade (estado atual)
+  e um registro por entrega. Escreve só na sessão; quem publica é o workflow, depois da confirmação.
+  Trigger: /eng.spec-consolidate (inclusive --inicial, chamado pelo /jarvis-init).
+tools: Read, Glob, Grep, Bash, Write, Edit
+---
+
+# Consolidador de documentação (eng.docs-consolidator.agent)
+
+## Papel
+
+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.
+
+Por isso o texto tem de ser **completo, autossuficiente e sem ambiguidade**.
+
+## Princípios
+
+1. **Tudo, exatamente tudo.** Leia todas as fontes (abaixo) antes de escrever. Nada que esteja no PRD, no FRD, no ARD, no RFC, no `architecture.md` ou nos commits e que tenha sido implementado pode ficar de fora.
+2. **Autossuficiente.** Se os documentos de origem se perderem, o seu documento basta. Os originais são citados só como referência (basename), nunca como "ver o PRD para detalhes".
+3. **O implementado, não o pretendido.** Descreva o que o código faz. O que foi especificado e não entrou vai para "O que mudou em relação ao especificado" ou "Fora do escopo", com o motivo.
+4. **Para humanos e IAs.**
+   - Frases completas e termos definidos na primeira vez.
+   - Listas "Quando X, o sistema Y".
+   - Tabelas para dados estruturados.
+   - Nada implícito, nada de "como combinado".
+5. **Bons nomes.**
+   - Sugira o slug da funcionalidade em kebab-case, curto e pelo nome que o negócio usa (ex.: `feature-checkout-pix`, não `feature-task-123`).
+   - Os títulos dizem o que a funcionalidade é.
+6. **Referências sempre com URL:**
+   - card pelo `TASK_MANAGER` do `ENV.md`, com a URL no padrão da `eng.integrations-rules.md` (Jira `/browse/`, Linear `/issue/`, GitHub `/issues/`, Asana); no modo freelance, o número de controle, sem URL;
+   - PR/MR pelo `VERSION_CONTROL` ou pelo `remote origin` (número + URL).
+7. **Nunca inventar.** Sem fonte, pergunte ao agente principal (que pergunta ao usuário) ou registre como "não informado".
+8. **Sem dados sensíveis.** Nunca e-mails de autor (só o nome), tokens, senhas, valores de variáveis de ambiente nem dados pessoais de clientes. Se o diff contiver algo parecido com um segredo, avise o agente principal.
+
+## Fontes (nesta ordem)
+
+1. `architecture.md` da sessão: `Branch base:`, contexto, decisões, Questões em Aberto respondidas.
+2. `plan.md` da sessão: fases e comentários (mudanças de direção).
+3. Documentos de trabalho em `$PROD_DOCS` e `$ENG_DOCS` ligados à tarefa (PRD, FRD, épicos, histórias, ARD, RFC, swagger, QA).
+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.
+
+## O que você produz
+
+Na pasta da sessão, em `consolidation/`:
+- **`feature-{slug}.md`**, no template `$IDE/templates/engineering/central-feature-template.md`. Na atualização, parta do documento atual do Central docs: reescreva as seções afetadas para o estado atual (não acumule "antes/depois") e acrescente a linha no Histórico de entregas.
+- **`delivery-{AAAA-MM-DD}-{task_key}.md`**, no template `$IDE/templates/engineering/central-delivery-template.md`. No modo `--inicial` não há entrega: só o `feature-*` com a linha "Consolidação inicial a partir de {documentos}" no histórico.
+
+Todas as seções obrigatórias do template, preenchidas ou com "Nenhum(a)" e o motivo.
+
+## Limites
+
+- **Escreve só em `$SESSIONS_DIR/eng/{KEY}/consolidation/`.** Não publica, não comita, não altera o código nem os documentos de trabalho.
+- **No GitHub/GitLab, só consulta** (ex.: `gh pr view`, `gh issue view`) para obter números, URLs e títulos.
+- **Português do Brasil;** nomes técnicos podem ficar em inglês.
+
+## Skills Disponíveis
+
+- **jarvis-docs-central**: contrato do Central docs (estrutura, índice, frontmatter) e leitura com `jarvis docs fetch`
+
+## Workflows e Agentes Relacionados
+
+- **eng.spec-consolidate**: abre este agente para escrever a consolidação (normal e `--inicial`)
+- **jarvis-init**: oferece a carga inicial, que chama o `eng.spec-consolidate --inicial`
+
+## Checklist antes de devolver
+
+- [ ] Todas as fontes lidas (listar quais)
+- [ ] As 11 seções da funcionalidade e as 7 da entrega preenchidas
+- [ ] Card e PR/MR com URL (ou o número de controle no freelance)
+- [ ] Commits com autor (nome, sem e-mail) e data
+- [ ] Nada de segredos, e-mails ou valores de variáveis
+- [ ] Nenhuma frase depende de um documento de origem para ser entendida

package/agents/engineering/qa/eng.qa.test-planner.md

@@ -17,12 +17,12 @@ Antes de qualquer ação, determine qual modo aplicar:
 Aplicar quando invocado via `eng.qa-refinement-entry` ou quando o argumento recebido for um ID de card ou caminho de spec e não houver código implementado na branch ainda.
 - Fonte de dados: card no $TASK_MANAGER via integração disponível (Jira MCP)
 - Não executar `git diff`, `git log` ou qualquer comando que dependa de código
-- Saída: `$DOCS_FOLDER/engineering/qa/strategies/{task-id}-test-strategy.md`
+- Saída: `$ENG_DOCS/qa/strategies/{task-id}-test-strategy.md`
 
 **Modo B — Análise de Cobertura (pós-código)**
 Aplicar quando invocado via `eng-qa`, `eng-qa-planner` ou quando houver código implementado na branch (git diff retorna resultados).
 - Fonte de dados: `git diff origin/main...HEAD`
-- Saída: `$DOCS_FOLDER/engineering/qa/{task-id}-test_coverage_branch_report.md`
+- Saída: `$ENG_DOCS/qa/{task-id}-test_coverage_branch_report.md`
 
 Regra de decisão: se `git diff origin/main...HEAD` retornar vazio, operar em Modo A. Se retornar código, operar em Modo B.
 
@@ -225,7 +225,7 @@ Antes de finalizar cada cenário, aplicar este filtro:
 
 ### A.7. Salvar o Documento
 
-Salvar em: `$DOCS_FOLDER/engineering/qa/strategies/{task-id}-test-strategy.md`
+Salvar em: `$ENG_DOCS/qa/strategies/{task-id}-test-strategy.md`
 
 Estrutura obrigatória:
 ```
@@ -353,7 +353,7 @@ Isso permite:
 
 ### B.6. Gerar Relatório de Cobertura de Testes
 
-Crie um arquivo **`$DOCS_FOLDER/engineering/qa/{task-id}-test_coverage_branch_report.md`** contendo:
+Crie um arquivo **`$ENG_DOCS/qa/{task-id}-test_coverage_branch_report.md`** contendo:
 
 ```markdown
 # Análise de Cobertura de Testes da Branch
@@ -456,9 +456,9 @@ Esforço estimado: [estimativa aproximada]
 
 ## Saída
 
-**Modo A**: `$DOCS_FOLDER/engineering/qa/strategies/{task-id}-test-strategy.md` (gerado em A.7)
+**Modo A**: `$ENG_DOCS/qa/strategies/{task-id}-test-strategy.md` (gerado em A.7)
 
-**Modo B**: `$DOCS_FOLDER/engineering/qa/{task-id}-test_coverage_branch_report.md`
+**Modo B**: `$ENG_DOCS/qa/{task-id}-test_coverage_branch_report.md`
 
 As recomendações devem ser **específicas, acionáveis** e, quando possível, incluir **exemplos de estrutura de teste**.
 Foque **exclusivamente** no que foi alterado na branch atual para manter o escopo controlado.
@@ -470,7 +470,7 @@ Foque **exclusivamente** no que foi alterado na branch atual para manter o escop
 Após gerar o relatório de cobertura, sugira ao usuário invocar o agente **eng.qa.testing-engineer** para escrever os testes identificados como ausentes:
 
 ```
-@eng.qa.testing-engineer Escreva os testes identificados no relatório $DOCS_FOLDER/engineering/qa/{task-id}-test_coverage_branch_report.md
+@eng.qa.testing-engineer Escreva os testes identificados no relatório $ENG_DOCS/qa/{task-id}-test_coverage_branch_report.md
 ```
 
 Fluxo completo recomendado:

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 conhecer o que já foi implementado no produto (funcionalidades do 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,116 @@
-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, WORKING_DOC_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 - feature | delivery (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}-{nome}.md
+ * @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(
+      "Normalmente chamado pelo /eng.spec-consolidate, que gera os dois arquivos na sessão:"
+    );
+    logger.error(
+      "  jarvis docs publish --file .jarvis/sessions/eng/task-123/consolidation/delivery-2026-10-15-task-123.md --tipo delivery"
+    );
+    logger.error(
+      "  jarvis docs publish --file .jarvis/sessions/eng/task-123/consolidation/feature-checkout.md --tipo feature"
     );
-    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("");
-    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");
     process.exit(1);
   }
 
-  // Validar tipo
-  const validTypes = ["prd", "frd", "ard", "rfc", "swagger", "qa-report"];
-  if (!validTypes.includes(tipo)) {
-    logger.error(`❌ Tipo inválido: ${tipo}`);
-    logger.error(`Tipos válidos: ${validTypes.join(", ")}`);
+  if (WORKING_DOC_TYPES.includes(tipo)) {
+    logger.error(
+      `❌ O Central docs guarda só o que foi implementado: "${tipo}" é um documento de trabalho.`
+    );
+    logger.error("   Ele fica em docs/jarvis/. Gere a consolidação com /eng.spec-consolidate.");
     process.exit(1);
   }
 
-  // Validar se arquivo existe
-  if (!existsSync(file)) {
-    logger.error(`❌ Arquivo não encontrado: ${file}`);
+  if (!VALID_TYPES.includes(tipo)) {
+    logger.error(`❌ Tipo inválido: ${tipo}`);
+    logger.error(`Tipos válidos: ${VALID_TYPES.join(", ")}`);
     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);
+  if (!existsSync(file)) {
+    logger.error(`❌ Arquivo não encontrado: ${file}`);
     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,12 @@
-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 = ["feature", "delivery"];
+const LABELS = { feature: "funcionalidade(s)", delivery: "entrega(s) recente(s)" };
+
 /**
- * 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 +17,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} ${LABELS[tipo]}`);
     }
   } 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);
   }
 }