jarvis-ai-framework 4.0.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 Central docs, quando `CENTRAL_DOCS_STORAGE` 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/commands/docs-publish.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { openStorageFromEnv } from "../lib/docs/fetch-file.js";
-import { publishFile, VALID_TYPES } from "../lib/docs/publish-file.js";
+import { publishFile, VALID_TYPES, WORKING_DOC_TYPES } from "../lib/docs/publish-file.js";
 import { logger, configureFromFlags } from "../lib/utils/logger.js";
 
 /**
@@ -9,9 +9,9 @@ import { logger, configureFromFlags } from "../lib/utils/logger.js";
  *
  * @param {Object} flags - Flags do comando
  * @param {string} flags.file - Caminho do arquivo local
- * @param {string} flags.tipo - Tipo do documento (ver VALID_TYPES)
+ * @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}-{id}-{nome}
+ * @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
@@ -33,13 +33,23 @@ export async function docsPublish(flags = {}) {
     logger.error(
       `Uso: jarvis docs publish --file <path> --tipo <${VALID_TYPES.join("|")}> [--produto <produto>] [--feature <slug>] [--squad <squad>]\n`
     );
-    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("  # Arquivo fora do padrão de nome:");
     logger.error(
-      "  jarvis docs publish --file ./docs/engineering/swagger/api.yaml --tipo swagger --feature api-wallet"
+      "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"
+    );
+    process.exit(1);
+  }
+
+  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);
   }
 

package/bin/commands/docs-sync.js

@@ -1,7 +1,8 @@
 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"];
+const COUNTED_TYPES = ["feature", "delivery"];
+const LABELS = { feature: "funcionalidade(s)", delivery: "entrega(s) recente(s)" };
 
 /**
  * Sincroniza a documentação do Central docs (lê `{SQUAD}/index.md` pelo adaptador).
@@ -55,7 +56,7 @@ export async function docsSync(flags = {}) {
 
     if (total > 0) {
       logger.info(`📊 ${total} documentos disponíveis:`);
-      for (const [tipo, n] of counts) logger.info(`   - ${n} ${tipo.toUpperCase()}(s)`);
+      for (const [tipo, n] of counts) logger.info(`   - ${n} ${LABELS[tipo]}`);
     }
   } catch (error) {
     logger.error("❌ Erro ao sincronizar docs:", error.message);

package/bin/lib/cli/program.js

@@ -132,12 +132,12 @@ export function buildProgram() {
 
   const docsPublishCmd = cmd(docs, "publish")
     .description(
-      "Publicar documento no Central docs (pasta: copia e regenera o índice; com git: branch + PR)"
+      "Publicar a consolidação (feature/delivery) 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|feat|epic|story|task|ard|rfc|swagger|qa-report")
+    .option("--tipo <tipo>", "feature|delivery (consolidação do /eng.spec-consolidate)")
     .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("--feature <slug>", "Só se o nome do arquivo fugir do padrão {tipo}-{nome}.md")
     .option("--squad <squad>", "Override do SQUAD do ENV.md")
     .option(
       "--workspace <workspace>",

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

@@ -1,8 +1,10 @@
 /**
- * @fileoverview Publica um documento no Central docs pelo adaptador configurado
- * (`CENTRAL_DOCS_STORAGE`). O destino segue a estrutura única
- * `{SQUAD}/{product|engineering}/{produto}/{arquivo}` e o índice do squad é
- * regenerado a cada publicação (ver `storage/build-index.js`).
+ * @fileoverview Publica no Central docs, pelo adaptador configurado
+ * (`CENTRAL_DOCS_STORAGE`), a consolidação do que foi implementado, gerada pelo
+ * `/eng.spec-consolidate`: o documento da funcionalidade (`feature-*.md`, em
+ * `{SQUAD}/product/{produto}/`) e o registro da entrega (`delivery-*.md`, em
+ * `{SQUAD}/engineering/{produto}/`). Documentos de trabalho (PRD, FRD, ARD, RFC…)
+ * não são publicados. O índice do squad é regenerado a cada publicação.
  * @module docs/publish-file
  */
 
@@ -12,18 +14,24 @@ import { logger } from "../utils/logger.js";
 
 /** @constant {Readonly<Record<string, "product"|"engineering">>} Área de cada tipo */
 export const AREA_BY_TYPE = Object.freeze({
-  prd: "product",
-  frd: "product",
-  feat: "product",
-  epic: "product",
-  story: "product",
-  task: "product",
-  ard: "engineering",
-  rfc: "engineering",
-  swagger: "engineering",
-  "qa-report": "engineering",
+  feature: "product",
+  delivery: "engineering",
 });
 
+/** @constant {ReadonlyArray<string>} Documentos de trabalho, que não vão mais para o Central docs */
+export const WORKING_DOC_TYPES = Object.freeze([
+  "prd",
+  "frd",
+  "feat",
+  "epic",
+  "story",
+  "task",
+  "ard",
+  "rfc",
+  "swagger",
+  "qa-report",
+]);
+
 /** @constant {ReadonlyArray<string>} Tipos aceitos pelo `jarvis docs publish` */
 export const VALID_TYPES = Object.freeze(Object.keys(AREA_BY_TYPE));
 
@@ -39,8 +47,8 @@ function assertSegment(label, value) {
 
 /**
  * Calcula o destino do documento no Central docs.
- * O nome é o do arquivo local quando ele já segue `{tipo}-…` (ex: `prd-001-checkout.md`);
- * senão vem de `--feature` (`{tipo}-{feature}.{ext}`).
+ * O nome é o do arquivo local quando ele já segue `{tipo}-…` (ex: `feature-checkout.md`,
+ * `delivery-2026-10-15-task-123.md`); senão vem de `--feature` (`{tipo}-{feature}.md`).
  *
  * @param {Object} p
  * @param {string} p.tipo
@@ -52,6 +60,12 @@ function assertSegment(label, value) {
  */
 export function resolveDestPath({ tipo, squad, produto, localFile, feature }) {
   const area = AREA_BY_TYPE[tipo];
+  if (!area && WORKING_DOC_TYPES.includes(tipo)) {
+    throw new Error(
+      `O Central docs guarda só o que foi implementado: "${tipo}" é um documento de trabalho e fica em docs/jarvis/.\n` +
+        "Gere a consolidação com /eng.spec-consolidate (tipos: feature, delivery)."
+    );
+  }
   if (!area) {
     throw new Error(`Tipo inválido: ${tipo}\nTipos válidos: ${VALID_TYPES.join(", ")}`);
   }
@@ -60,7 +74,7 @@ export function resolveDestPath({ tipo, squad, produto, localFile, feature }) {
 
   const local = basename(localFile);
   const ext = extname(local).toLowerCase() || ".md";
-  const followsPattern = local.toLowerCase().startsWith(`${tipo}-`) && /\.(md|ya?ml|json)$/.test(ext);
+  const followsPattern = local.toLowerCase().startsWith(`${tipo}-`) && ext === ".md";
 
   let fileName;
   if (followsPattern) {
@@ -70,7 +84,7 @@ export function resolveDestPath({ tipo, squad, produto, localFile, feature }) {
     fileName = `${tipo}-${feature}${ext}`;
   } else {
     throw new Error(
-      `O arquivo "${local}" não segue o padrão {tipo}-{id}-{nome}${ext}.\n` +
+      `O arquivo "${local}" não segue o padrão ${tipo}-{nome}.md.\n` +
         `Renomeie o arquivo ou informe --feature <slug>.`
     );
   }
@@ -97,12 +111,9 @@ export async function publishFile({ storage, localFile, tipo, squad, produto, fe
 
   const { destPath } = resolveDestPath({ tipo, squad, produto, localFile, feature });
 
-  const isStructuredSwagger = tipo === "swagger" && !localFile.toLowerCase().endsWith(".md");
-  if (!isStructuredSwagger) {
-    logger.info("Validando frontmatter...");
-    validateFrontmatter(localFile, tipo);
-    logger.info("✅ Frontmatter válido");
-  }
+  logger.info("Validando frontmatter...");
+  validateFrontmatter(localFile, tipo);
+  logger.info("✅ Frontmatter válido");
 
   logger.info("");
   logger.info("📋 Resumo da Publicação:");

package/bin/lib/docs/storage/build-index.js

@@ -1,6 +1,6 @@
 /**
  * @fileoverview Gera o `{SQUAD}/index.md` do Central docs a partir do frontmatter
- * dos documentos. O índice é sempre regenerado pela listagem (nunca editado), para
+ * da consolidação (funcionalidades e entregas). O índice é sempre regenerado pela listagem (nunca editado), para
  * duas publicações seguidas não apagarem a entrada uma da outra.
  * @module docs/storage/build-index
  */
@@ -27,9 +27,20 @@ export function walkFiles(dir) {
     });
 }
 
+/** @constant {Readonly<Record<string, {prefix: string, title: string}>>} O que cada área lista no índice */
+export const INDEXED = Object.freeze({
+  product: { prefix: "feature-", title: "Funcionalidades (estado atual)" },
+  engineering: { prefix: "delivery-", title: "Entregas recentes" },
+});
+
+/** @constant {number} Entregas listadas por produto (as mais recentes; o nome começa pela data) */
+export const MAX_DELIVERIES_PER_PRODUCT = 10;
+
 /**
- * Monta o conteúdo do índice de um squad.
- * Formato: `# SQUAD` › `## área` › `### produto` › `- [arquivo](caminho) | vX | status | nome`.
+ * Monta o conteúdo do índice de um squad. Lista só a consolidação do
+ * `/eng.spec-consolidate`: funcionalidades (`feature-*`) e as entregas mais recentes
+ * (`delivery-*`). Outros arquivos (ex.: PRD/ARD publicados na 4.0.0) ficam fora.
+ * Formato: `# SQUAD` › `## área` › `### produto` › `- [arquivo](caminho) | status | nome | atualizado`.
  * @param {string} root - Pasta do Central docs
  * @param {string} squad
  * @returns {string}
@@ -38,9 +49,13 @@ export function renderIndex(root, squad) {
   const out = [`# ${squad}`, ""];
 
   for (const area of AREAS) {
+    const { prefix, title } = INDEXED[area];
     const areaDir = join(root, squad, area);
-    const files = walkFiles(areaDir).filter((f) => !f.endsWith(`${sep}index.md`));
-    out.push(`## ${area}`, "");
+    const files = walkFiles(areaDir).filter((f) => {
+      const name = f.split(sep).pop();
+      return name.startsWith(prefix) && name.endsWith(".md");
+    });
+    out.push(`## ${area}`, "", `> ${title}`, "");
     if (files.length === 0) {
       out.push("_Nenhum documento._", "");
       continue;
@@ -55,15 +70,21 @@ export function renderIndex(root, squad) {
     }
 
     for (const [product, productFiles] of byProduct) {
+      const listed =
+        area === "engineering"
+          ? [...productFiles].sort().reverse().slice(0, MAX_DELIVERIES_PER_PRODUCT)
+          : productFiles;
       out.push(`### ${product}`);
-      for (const file of productFiles) {
+      for (const file of listed) {
         const rel = relative(join(root, squad), file).split(sep).join("/");
         const name = rel.split("/").pop();
-        const meta = file.endsWith(".md") ? parseFrontmatter(readFileSync(file, "utf-8")) : {};
+        const meta = parseFrontmatter(readFileSync(file, "utf-8"));
         let line = `- [${name}](${rel})`;
-        if (meta.version) line += ` | v${meta.version}`;
         if (meta.status) line += ` | ${meta.status}`;
         if (meta.name) line += ` | ${meta.name}`;
+        if (meta.task_key) line += ` | ${meta.task_key}`;
+        const when = meta.updated_at || meta.date;
+        if (when) line += ` | ${when}`;
         out.push(line);
       }
       out.push("");

package/bin/lib/docs/validate-frontmatter.js

@@ -80,6 +80,10 @@ export function validateFrontmatter(filePath, tipo) {
  */
 function getRequiredFields(tipo) {
   const fields = {
+    // Consolidação do Central docs (/eng.spec-consolidate)
+    feature: ['id', 'name', 'status', 'product', 'updated_at'],
+    delivery: ['id', 'feature', 'task_key', 'pr', 'date'],
+    // Documentos de trabalho (validação usada fora do publish)
     prd: ['id', 'name', 'version', 'status'],
     frd: ['id', 'name', 'version', 'status', 'related_prd'],
     feat: ['id', 'name', 'version', 'status', 'related_prd'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jarvis-ai-framework",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Jarvis framework",
   "type": "module",
   "bin": {

package/rules/engineering/eng.docs-scraping-rules.md

@@ -18,8 +18,8 @@ Aplicável sempre que um robô novo for implementado, um bug estrutural for reso
 
 #### Localização
 
-- Sempre criar em `docs/engineering/robots/{robot-tag}-robot.md`
-- Exemplos: `docs/engineering/robots/consulta-orgao-robot.md`, `docs/engineering/robots/extrator-dados-robot.md`
+- Sempre criar em `$ENG_DOCS/robots/{robot-tag}-robot.md`
+- Exemplos: `$ENG_DOCS/robots/consulta-orgao-robot.md`, `$ENG_DOCS/robots/extrator-dados-robot.md`
 
 #### Conteúdo obrigatório
 
@@ -44,7 +44,7 @@ Todo arquivo `{robot-tag}-robot.md` deve conter:
 
 ### Proibido
 
-- ❌ Criar em `docs/robots/` — pasta incorreta, usar `docs/engineering/robots/`
+- ❌ Criar em `docs/robots/` — pasta incorreta, usar `$ENG_DOCS/robots/`
 - ❌ Omitir a seção de **Limitações Conhecidas** — é fundamental para evitar que outros devs tentem implementar algo impossível
 - ❌ Omitir o **Histórico de Bugs** — descobertas custam tempo; documentar evita retrabalho
 
@@ -61,4 +61,4 @@ Nenhuma — todo robô deve ter sua documentação, independente do tamanho ou c
 
 ## Referências
 
-- `docs/engineering/robots/{robot-tag}-robot.md` — referência de implementação completa
+- `$ENG_DOCS/robots/{robot-tag}-robot.md` — referência de implementação completa

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

@@ -37,7 +37,7 @@ Com board definido, se o key não veio nos argumentos, perguntar o id do card na
 
 Só se `TASK_MANAGER` estiver preenchido com um vendor. Freelance → pular. Falha no comentário não bloqueia o workflow.
 
-Comentar **somente** em eventos relevantes: (a) **desvio do plano** (mudança de direção, fase bloqueada), (b) **auditoria do Advisor** (as questões do `architecture.md` com as opções junto da escolha), (c) **bloqueio** com valor de rastreabilidade (ex.: pré-PR reprovado), (d) **link do MR**, uma única vez. **Nunca** comentar início ou fim de etapa ("Iniciando…", "concluído…"): o acompanhamento fica no fluxo e no PR.
+Comentar **somente** em eventos relevantes: (a) **desvio do plano** (mudança de direção, fase bloqueada), (b) **auditoria do Advisor** (as questões do `architecture.md` com as opções junto da escolha), (c) **bloqueio** com valor de rastreabilidade, (d) **link do MR**, uma única vez, (e) o **`gate-checklist.md` do `eng.pre-pr`**, só se o usuário responder Sim. **Nunca** comentar início ou fim de etapa ("Iniciando…", "concluído…"): o acompanhamento fica no fluxo e no PR.
 
 ```
 /eng-global-task-comment {TASK_MANAGER_KEY} {mensagem}

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

@@ -188,7 +188,7 @@ Quando o robô interage com interface visual (browser headless), usar a especial
 
 Seguir `$IDE/rules/engineering/eng.docs-scraping-rules.md` sem exceções.
 
-Criar ou atualizar `docs/engineering/robots/{robot-tag}-robot.md` com:
+Criar ou atualizar `$ENG_DOCS/robots/{robot-tag}-robot.md` com:
 - Visão Geral (o que coleta e o que **não** coleta)
 - Fluxo de Execução (sequência de passos com URLs)
 - Fontes de Dados e Campos Extraídos

package/rules/product/prod-rules.md

@@ -39,20 +39,20 @@ PROD_FOLDER_NAME=product
 PROD_RULES=$RULES_FOLDER/$PROD_FOLDER_NAME
 PROD_FLOWS=.$IDE/$FLOWS_FOLDER
 PROD_TEMPLATES=.$IDE/$TEMPLATES_FOLDER/$PROD_FOLDER_NAME
-PROD_DOCS=$DOCS_FOLDER/$PROD_FOLDER_NAME
+PROD_DOCS=$DOCS_FOLDER/jarvis/$PROD_FOLDER_NAME
 ```
 
 Abaixo, segue uma descrição de algumas das variáveis mais importantes para as rotinas de produto:
 
 - $DOCS_FOLDER é o nome da pasta principal de documentações do projeto. Ela fica localizada na raiz do projeto.
-- $PROD_DOCS é o nome da pasta principal de documentações de produto do projeto. No projeto único (sem workspace), fica em `docs/jarvis/product`, fora do versionamento do código.
+- $PROD_DOCS é a pasta dos documentos de produto gerados pelos comandos (PRD, FRD, épicos, histórias, discovery): `$JARVIS_DOCS/product` (`docs/jarvis/product`), nos dois modos de trabalho e fora do versionamento do código. Os de engenharia ficam em `$ENG_DOCS` (`docs/jarvis/engineering`).
 - $PROD_FOLDER_NAME é o nome padrão da pasta de produto que será usada em diversos contextos do projeto.
 - $TEMPLATES_FOLDER é o nome da pasta principal de templates do projeto.
 - $PROD_TEMPLATES é o caminho completo para os templates de produto.
 - $FLOWS_FOLDER é o nome da pasta de workflows e comandos utilizados pelos IDEs. (tenha em mente que o nome da pasta pode variar de acordo com a IDE utilizada)
 - $RULES_FOLDER é o nome da pasta principal de regras invioláveis que os agentes devem seguir.
 - $PROD_RULES é o caminho para a pasta que contém as regras de produto. Leia todos os arquivos dentro dessa pasta para entender as regras de produto.
-- $CENTRAL_DOCS_STORAGE e $CENTRAL_DOCS_LOCATION configuram o Central docs (opcional): onde ficam as especificações aprovadas e o índice global de todas elas. Vazio = desligado. Hoje o único armazenamento é `filesystem` (uma pasta; se tiver `.git`, publica por PR). Leitura e publicação sempre por `jarvis docs fetch | sync | publish`.
+- $CENTRAL_DOCS_STORAGE e $CENTRAL_DOCS_LOCATION configuram o Central docs: o registro do que **foi implementado** (um documento por funcionalidade e um por entrega, gerados pelo `/eng.spec-consolidate`), com um índice global. Ligado por padrão (`filesystem`); vazio = desligado. Os documentos de trabalho (PRD, FRD, ARD, RFC) não são publicados lá. Leitura e publicação sempre por `jarvis docs fetch | sync | publish`.
 
 
 ## VARIÁVEL `$IDE` - DETECÇÃO AUTOMÁTICA DA PASTA DA IDE

package/rules-on-demand/engineering/eng.pr-rules.md

@@ -279,7 +279,7 @@ O MR deve seguir o template em `$IDE/templates/engineering/PR-template.md`:
 - ✅ Verificar `git status` antes do commit
 - ✅ Usar mensagens de commit descritivas
 - ✅ Referenciar o TASK_MANAGER_KEY no commit
-- ✅ **Limpar sessão após criar MR**
+- ✅ Gerar o `pull-request.md` na sessão e publicar só com o **Sim**
 
 ---
 
@@ -316,40 +316,18 @@ Antes de considerar o PR completo:
 - [ ] Arquivos adicionados individualmente (não `git add .`)
 - [ ] Commit com mensagem padronizada
 - [ ] Commit referencia o TASK_MANAGER_KEY
-- [ ] Push realizado
-- [ ] MR criado com template preenchido
+- [ ] Push realizado (só com o Sim)
+- [ ] MR criado a partir do `pull-request.md` (só com o Sim)
 - [ ] Branch de destino correta
 - [ ] Card do Jira movido para "In Review"
 - [ ] Comentários de code review processados
-- [ ] **Sessão limpa** (`$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/` removida)
+- [ ] `pull-request.md` aprovado na sessão (e publicado, se o usuário respondeu Sim)
+- [ ] Lembrete do `/eng.spec-consolidate` na mensagem final
 
 ---
 
-## Limpeza da Sessão
+## Sessão e publicação
 
-### Por que limpar?
-
-1. **Evitar poluição**: Sessões antigas ocupam espaço e confundem
-2. **Fonte da verdade**: A documentação oficial está no Jira e no MR
-3. **Organizacão**: Manter apenas sessões ativas
-
-### O que é removido?
-
-```
-$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/
-├── architecture.md    → Removido
-├── plan.md            → Removido
-└── context.md         → Removido (se existir)
-```
-
-### Onde a documentação permanece?
-
-- **Card do Jira**: Tech spec anexada, comentários
-- **Merge Request**: Descrição, histórico de commits
-- **Código**: Comentários inline, docstrings
-
-### Comando de limpeza
-
-```bash
-rm -rf $SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/
-```
+- O texto do PR fica em **`$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/pull-request.md`**, aprovado pelo usuário.
+- **Publicar (push + MR/PR) só com o Sim** do `AskUserQuestion` "Publicar o PR agora?". Com Não, o arquivo fica na sessão e nada é enviado.
+- **A sessão nunca é apagada por este comando:** o `/eng.spec-consolidate`, que roda em seguida, precisa do `architecture.md`, do `plan.md`, do `gate-checklist.md` e do `pull-request.md`. A pessoa apaga à mão quando quiser.

package/rules-on-demand/engineering/eng.pre-pr-rules.md

@@ -63,25 +63,21 @@ Confirmar que está na branch certa? (s/n)
 
 ## Regras de Validação
 
+### Só revisar
+
+O `eng.pre-pr` **aponta lacunas e não corrige nada**: não altera código, não escreve testes, não atualiza documentação e não publica no Central docs. Quem decide o que ajustar é o usuário.
+
 ### Escopo de Análise
 
-Avaliar **apenas** as mudanças da branch atual em relação ao branch base (`main`/`develop`):
+Avaliar **apenas** as mudanças da branch atual em relação à branch base (`Branch base:` do `architecture.md`; sem ele, perguntar):
 
 ```bash
-git diff main...HEAD
+git diff {BRANCH_BASE}...HEAD
 ```
 
 ### Evidências Obrigatórias
 
-Ao citar "testes passando" ou "validações OK", incluir:
-- Qual comando foi executado
-- Output do resultado (ou smoke test manual se não houver suíte)
-
-### Revalidação após Mudanças
-
-Se qualquer gate levar a mudanças de código, reexecutar obrigatoriamente:
-- Revisão técnica do código alterado
-- Testes/validações
+Cada lacuna cita onde está (`arquivo:linha`) ou o comando que a revelou e o resultado.
 
 ---
 
@@ -89,11 +85,8 @@ Se qualquer gate levar a mudanças de código, reexecutar obrigatoriamente:
 
 O workflow **deve sempre** terminar com:
 
-1. **Semáforo de status**:
-   - 🟢 Green: pronto para PR
-   - 🟡 Yellow: pode abrir PR com ressalvas documentadas
-   - 🔴 Red: bloqueado — listar o que impede o PR
-
-2. **Comentário no card só se a validação reprovar** (🔴 RED, bloqueio), com o motivo (via `/eng-global-task-comment`) — pular se freelance; GREEN e YELLOW não comentam
-
-3. **Aguardar permissão explícita** do usuário para prosseguir para `/eng.pr`
+1. **`gate-checklist.md`** em `$SESSIONS_DIR/eng/{TASK_MANAGER_KEY}/`:
+   - semáforo (🟢 / 🟡 / 🔴), resumo, lacunas por área (o quê, onde, por que importa, sugestão, severidade, **Decisão**), evidências e PR Brief.
+2. **Decisões do usuário** gravadas na coluna Decisão (Ajustar / Não ajustar + motivo).
+3. **Pergunta Sim / Não** (`AskUserQuestion`) para publicar o relatório como comentário na issue/card (`/eng-global-task-comment`). Nunca publicar sem a resposta. Freelance: só na sessão.
+4. **Aguardar permissão explícita** do usuário para prosseguir para `/eng.pr`.

package/skills/eng-backend-arch-c4/SKILL.md

@@ -42,7 +42,7 @@ Criar e manter documentação de arquitetura usando os 4 níveis do C4:
 
 - **Script de detecção**: `$IDE/scripts/detect-stack.sh`
 - **Template**: `$IDE/templates/engineering/c4-model-template.md`
-- **Saída**: `$DOCS_FOLDER/engineering/c4/`
+- **Saída**: `$ENG_DOCS/c4/`
 
 ### Exemplos de Output
 
@@ -84,7 +84,7 @@ Code      -> Quais classes/interfaces críticas?
 ### 1. Verificar Documentação Existente
 
 ```bash
-ls -la $DOCS_FOLDER/engineering/c4/ 2>/dev/null || echo "Nenhum diagrama C4"
+ls -la $ENG_DOCS/c4/ 2>/dev/null || echo "Nenhum diagrama C4"
 ls -la $DOCS_FOLDER/architecture/adr/ 2>/dev/null
 ```
 
@@ -318,7 +318,7 @@ git diff origin/main --name-only | grep -E "docker|config|src/(domain|infrastruc
 ```
 ✅ Diagrama C4 criado/atualizado!
 
-📄 Arquivo: $DOCS_FOLDER/engineering/c4/{arquivo}.md
+📄 Arquivo: $ENG_DOCS/c4/{arquivo}.md
 📊 Nível: {nivel}
 🏗️ Sistema: {nome}