jarvis-ai-framework 3.2.0 → 5.0.0

package/bin/lib/docs/storage/filesystem.js

@@ -0,0 +1,203 @@
+/**
+ * @fileoverview Adaptador `filesystem` do Central docs: uma pasta do disco
+ * (dentro do workspace ou em qualquer caminho). Se a pasta tiver `.git` (clone
+ * de um repositório de documentação), liga a camada git: `pull` antes de ler e
+ * branch + commit + push + PR ao publicar.
+ *
+ * Todo comando externo usa `execFileSync` com argumentos (sem shell), e todo
+ * caminho recebido é resolvido dentro da pasta (sem `..`).
+ * @module docs/storage/filesystem
+ */
+
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createMergeRequest as defaultCreateMergeRequest } from "../../vcs/api.js";
+import { logger } from "../../utils/logger.js";
+import { buildIndex, walkFiles } from "./build-index.js";
+
+/**
+ * Executa `git` na pasta informada, sem shell.
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {string} stdout sem espaços nas pontas
+ */
+export function runGit(args, cwd) {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+/**
+ * Resolve um caminho relativo dentro de `root`, rejeitando o que sair dela.
+ * @param {string} root
+ * @param {string} rel
+ * @returns {string} caminho absoluto
+ * @throws {Error} caminho absoluto, com `..` que escape da pasta, ou vazio
+ */
+export function safePath(root, rel) {
+  if (!rel || isAbsolute(rel)) {
+    throw new Error(`Caminho inválido para o Central docs: "${rel}"`);
+  }
+  const full = resolve(root, rel);
+  const fromRoot = relative(root, full);
+  if (fromRoot === "" || fromRoot.startsWith("..") || isAbsolute(fromRoot)) {
+    throw new Error(`Caminho fora da pasta do Central docs: "${rel}"`);
+  }
+  return full;
+}
+
+/**
+ * @param {Object} cfg
+ * @param {string} cfg.location - Pasta do Central docs (absoluta)
+ * @param {string} [cfg.ref] - Branch lida no `pull` (CENTRAL_DOCS_REF)
+ * @param {string} [cfg.targetBranch] - Branch base do PR (CENTRAL_DOCS_TARGET_BRANCH)
+ * @param {string} [cfg.reviewers] - Revisores (vão na descrição do PR)
+ * @param {Object} [cfg.deps] - `runGit` e `createMergeRequest` injetáveis (testes)
+ */
+export function createFilesystemStorage({
+  location,
+  ref = "main",
+  targetBranch = "main",
+  reviewers = "",
+  deps = {},
+}) {
+  const git = deps.runGit ?? runGit;
+  const createMergeRequest = deps.createMergeRequest ?? defaultCreateMergeRequest;
+  const isGit = existsSync(join(location, ".git"));
+  let pulled = false;
+
+  /** `git pull --ff-only` uma vez por instância; falha vira aviso e a leitura segue local. */
+  function pullOnce() {
+    if (!isGit || pulled) return;
+    pulled = true;
+    try {
+      git(["pull", "--ff-only", "origin", ref], location);
+    } catch (error) {
+      logger.warn(`⚠️  Não foi possível atualizar o Central docs (git pull): ${error.message.split("\n")[0]}`);
+      logger.warn("   Usando a cópia local.");
+    }
+  }
+
+  function ensureLocation() {
+    if (!existsSync(location)) {
+      throw new Error(
+        `Pasta do Central docs não encontrada: ${location}\nCrie a pasta ou ajuste CENTRAL_DOCS_LOCATION no ENV.md (/jarvis-init).`
+      );
+    }
+  }
+
+  return {
+    kind: "filesystem",
+    location,
+    isGit,
+
+    /**
+     * Lê um documento.
+     * @param {string} path - Caminho dentro do Central docs (ex: `CORE/index.md`)
+     * @returns {Promise<string>}
+     * @throws {Error} com `code = 404` se o arquivo não existir
+     */
+    async fetch(path) {
+      ensureLocation();
+      pullOnce();
+      const full = safePath(location, path);
+      if (!existsSync(full)) {
+        const err = new Error(`Arquivo não encontrado no Central docs: ${path}`);
+        err.code = 404;
+        throw err;
+      }
+      return readFileSync(full, "utf-8");
+    },
+
+    /**
+     * Lista os `.md` sob um prefixo.
+     * @param {string} prefix
+     * @returns {Promise<string[]>} caminhos relativos à pasta, com `/`
+     */
+    async list(prefix) {
+      ensureLocation();
+      pullOnce();
+      return walkFiles(safePath(location, prefix))
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => relative(location, f).split(sep).join("/"));
+    },
+
+    /**
+     * Regenera `{squad}/index.md`. Com `.git` e `scripts/build-index.sh` no repositório,
+     * usa o script dele (o CI do repositório confere o índice com ele).
+     * @param {string} squad
+     * @returns {string} caminho relativo do índice
+     */
+    buildIndex(squad) {
+      const script = join(location, "scripts", "build-index.sh");
+      if (isGit && existsSync(script)) {
+        execFileSync("bash", [script], { cwd: location, stdio: ["ignore", "pipe", "pipe"] });
+      } else {
+        buildIndex(location, squad);
+      }
+      return `${squad}/index.md`;
+    },
+
+    /**
+     * Grava um documento e regenera o índice do squad.
+     * Sem `.git`: copia e pronto. Com `.git`: branch → cópia → índice → commit → push → PR.
+     * @param {Object} p
+     * @param {string} p.localFile - Arquivo de origem
+     * @param {string} p.destPath - Destino dentro do Central docs (`{SQUAD}/{área}/{produto}/{arquivo}`)
+     * @param {string} p.squad
+     * @param {string} p.tipo
+     * @returns {Promise<{ destPath: string, indexPath: string, sha?: string, branch?: string, mr?: Object }>}
+     */
+    async publish({ localFile, destPath, squad, tipo }) {
+      ensureLocation();
+      const dest = safePath(location, destPath);
+
+      if (!isGit) {
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(localFile, dest);
+        const indexPath = this.buildIndex(squad);
+        return { destPath, indexPath };
+      }
+
+      const branch = `docs/${destPath.replace(extname(destPath), "")}`;
+      git(["checkout", targetBranch], location);
+      try {
+        git(["pull", "--ff-only", "origin", targetBranch], location);
+      } catch (error) {
+        logger.warn(`⚠️  git pull falhou (${error.message.split("\n")[0]}); seguindo com a cópia local.`);
+      }
+      git(["checkout", "-b", branch], location);
+
+      try {
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(localFile, dest);
+        const indexPath = this.buildIndex(squad);
+        git(["add", "--", destPath, indexPath], location);
+        git(["commit", "-m", `docs(${squad}): add ${tipo} ${basename(destPath)}`], location);
+        const sha = git(["rev-parse", "HEAD"], location);
+
+        git(["push", "-u", "origin", branch], location);
+        const remoteUrl = git(["remote", "get-url", "origin"], location);
+        let description = `## Documento\n\n- **Tipo**: ${tipo}\n- **Arquivo**: \`${destPath}\``;
+        if (reviewers) description += `\n- **Revisores**: ${reviewers}`;
+        const mr = await createMergeRequest(remoteUrl, {
+          source: branch,
+          target: targetBranch,
+          title: `docs(${squad}): ${tipo} ${basename(destPath)}`,
+          description,
+        });
+
+        return { destPath, indexPath, sha, branch, mr };
+      } finally {
+        try {
+          git(["checkout", targetBranch], location);
+        } catch {
+          // a branch de trabalho fica; o erro original (se houver) é o que importa
+        }
+      }
+    },
+  };
+}

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

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Fábrica dos adaptadores de armazenamento do Central docs.
+ * O valor de `CENTRAL_DOCS_STORAGE` escolhe o adaptador; `CENTRAL_DOCS_LOCATION`
+ * diz onde ele guarda. Hoje só existe o `filesystem` (com camada git opcional);
+ * S3 e Google Drive são as issues #144 e #145.
+ * @module docs/storage
+ */
+
+import { isAbsolute, resolve } from "node:path";
+import { createFilesystemStorage } from "./filesystem.js";
+
+/** @constant {ReadonlyArray<string>} Adaptadores disponíveis */
+export const SUPPORTED_STORAGES = Object.freeze(["filesystem"]);
+
+/**
+ * Erro de configuração do Central docs (variável ausente, valor não suportado).
+ */
+export class StorageConfigError extends Error {}
+
+/**
+ * Resolve `CENTRAL_DOCS_LOCATION` a partir da pasta do workspace (a que contém `$IDE/`).
+ * @param {string} location
+ * @param {string} root - Pasta do workspace
+ * @returns {string} caminho absoluto
+ */
+export function resolveLocation(location, root) {
+  return isAbsolute(location) ? location : resolve(root, location);
+}
+
+/**
+ * Devolve o adaptador configurado no ENV.md, ou `null` se o Central docs estiver desligado.
+ *
+ * @param {Record<string, string>} env - Variáveis do ENV.md (`loadEnv`)
+ * @param {Object} opts
+ * @param {string} opts.root - Pasta do workspace (`resolveEnvPath(...).root`)
+ * @param {Object} [opts.deps] - Dependências injetáveis (testes): `runGit`, `createMergeRequest`
+ * @returns {ReturnType<typeof createFilesystemStorage> | null}
+ * @throws {StorageConfigError} valor de STORAGE não suportado, LOCATION ausente ou variável antiga
+ */
+export function getStorage(env, { root, deps } = {}) {
+  const storage = (env.CENTRAL_DOCS_STORAGE || "").trim().toLowerCase();
+
+  if (!storage) {
+    if (env.CENTRAL_DOCS_REPO) {
+      throw new StorageConfigError(
+        "CENTRAL_DOCS_REPO não é mais usado. Rode o /jarvis-init e escolha Upgrade (C) para migrar " +
+          "para CENTRAL_DOCS_STORAGE + CENTRAL_DOCS_LOCATION."
+      );
+    }
+    return null;
+  }
+
+  if (!SUPPORTED_STORAGES.includes(storage)) {
+    throw new StorageConfigError(
+      `Armazenamento "${storage}" ainda não suportado. Use: ${SUPPORTED_STORAGES.join(", ")}.`
+    );
+  }
+
+  if (!env.CENTRAL_DOCS_LOCATION) {
+    throw new StorageConfigError(
+      "CENTRAL_DOCS_LOCATION não definido no ENV.md (pasta do Central docs)."
+    );
+  }
+  if (!root) {
+    throw new StorageConfigError("getStorage: pasta do workspace (root) não informada.");
+  }
+
+  return createFilesystemStorage({
+    location: resolveLocation(env.CENTRAL_DOCS_LOCATION, root),
+    ref: env.CENTRAL_DOCS_REF || "main",
+    targetBranch: env.CENTRAL_DOCS_TARGET_BRANCH || "main",
+    reviewers: env.CENTRAL_DOCS_REVIEWERS || "",
+    deps,
+  });
+}

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

@@ -2,10 +2,10 @@ import { readFileSync } from 'node:fs'
 import { parseFrontmatter, extractFrontmatterBlock } from '../utils/frontmatter.js'
 
 /**
- * Valida frontmatter YAML de documentos (PRD, FRD, ARD, RFC)
+ * Valida frontmatter YAML de documentos (PRD, FRD, épico, história, tarefa, ARD, RFC)
  * 
  * @param {string} filePath - Caminho do arquivo
- * @param {string} tipo - Tipo do documento (prd|frd|ard|rfc)
+ * @param {string} tipo - Tipo do documento (ver VALID_TYPES em publish-file.js)
  * @returns {Object} Metadados extraídos
  * @throws {Error} Se frontmatter for inválido
  */
@@ -54,7 +54,13 @@ export function validateFrontmatter(filePath, tipo) {
   }
 
   // Validar status
-  const validStatuses = ['icebox', 'in_review', 'in_progress', 'in_production', 'deprecated', 'Proposta', 'Em desenvolvimento', 'Em validação', 'Finalizada', 'Draft', 'In Review', 'Ready for Decision', 'Accepted', 'Rejected', 'Superseded']
+  // Produto (rules/product/prod-rules.md), ARD (templates/engineering/ARD-template.md),
+  // discovery (prod-discovery-template.md) e RFC (RFC-template.md)
+  const validStatuses = [
+    'icebox', 'in_review', 'backlog', 'in_progress', 'in_production', 'cancelled', 'deprecated',
+    'proposed', 'approved',
+    'Draft', 'In Review', 'Ready for Decision', 'Accepted', 'Rejected', 'Superseded'
+  ]
   
   if (metadata.status && !validStatuses.includes(metadata.status)) {
     console.warn(
@@ -74,9 +80,17 @@ 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'],
-    ard: ['Status', 'Data', 'Autor', 'Versão'],
+    feat: ['id', 'name', 'version', 'status', 'related_prd'],
+    epic: ['id', 'name', 'version', 'status', 'related_prd'],
+    story: ['id', 'name', 'status', 'related_prd'],
+    task: ['id', 'name', 'status'],
+    ard: ['id', 'name', 'version', 'status'],
     rfc: ['Status', 'Criado em', 'Proponente'],
     'qa-report': ['period', 'squad', 'version']
   }

package/bin/lib/vcs/api.js

@@ -37,39 +37,6 @@ async function request(url, { method = "GET", headers = {}, body } = {}) {
   return { ok: res.ok, status: res.status, json, text };
 }
 
-export async function fetchRawFile(repoUrl, filePath, ref = "main") {
-  const repo = parseRepoUrl(repoUrl);
-  const token = getVcsToken(repo.vendor);
-  const headers = authHeaders(repo.vendor, token);
-  const encodedPath = encodeURIComponent(filePath);
-
-  let url;
-  if (repo.vendor === "gitlab") {
-    url = `${repo.apiBase}/projects/${repo.projectPathEncoded}/repository/files/${encodedPath}/raw?ref=${encodeURIComponent(ref)}`;
-  } else if (repo.vendor === "github") {
-    url = `${repo.apiBase}/repos/${repo.owner}/${repo.repo}/contents/${filePath}?ref=${encodeURIComponent(ref)}`;
-    headers.Accept = "application/vnd.github.raw";
-  } else {
-    url = `${repo.apiBase}/repositories/${repo.owner}/${repo.repo}/src/${encodeURIComponent(ref)}/${filePath}`;
-  }
-
-  const res = await fetch(url, { headers });
-  if (res.status === 404) {
-    const err = new Error(`not_found:${filePath}`);
-    err.code = 404;
-    throw err;
-  }
-  if (res.status === 401 || res.status === 403) {
-    const err = new Error(`unauthorized:${repo.vendor}`);
-    err.code = res.status;
-    throw err;
-  }
-  if (!res.ok) {
-    throw new Error(`fetch failed ${res.status}: ${await res.text()}`);
-  }
-  return await res.text();
-}
-
 export async function createMergeRequest(repoUrl, opts) {
   const { source, target, title, description = "" } = opts;
   const repo = parseRepoUrl(repoUrl);
@@ -141,98 +108,6 @@ export async function createMergeRequest(repoUrl, opts) {
   };
 }
 
-/**
- * Commit de um ou mais arquivos numa branch nova (docs publish).
- * files: [{ path, contentBase64, action: 'create'|'update' }]
- */
-export async function commitFiles(repoUrl, opts) {
-  const { branch, startBranch, message, files } = opts;
-  const repo = parseRepoUrl(repoUrl);
-  const token = getVcsToken(repo.vendor);
-  const headers = authHeaders(repo.vendor, token);
-
-  if (repo.vendor === "gitlab") {
-    const { ok, status, json } = await request(
-      `${repo.apiBase}/projects/${repo.projectPathEncoded}/repository/commits`,
-      {
-        method: "POST",
-        headers,
-        body: {
-          branch,
-          start_branch: startBranch,
-          commit_message: message,
-          actions: files.map((f) => ({
-            action: f.action || "create",
-            file_path: f.path,
-            content: f.contentBase64,
-            encoding: "base64",
-          })),
-        },
-      }
-    );
-    if (!ok || !json?.id) {
-      throw new Error(`Falha no commit GitLab (${status}): ${JSON.stringify(json)}`);
-    }
-    return { sha: json.id };
-  }
-
-  if (repo.vendor === "github") {
-    const refRes = await request(
-      `${repo.apiBase}/repos/${repo.owner}/${repo.repo}/git/ref/heads/${startBranch}`,
-      { headers }
-    );
-    if (!refRes.ok) {
-      throw new Error(`Branch ${startBranch} não encontrada no GitHub (${refRes.status})`);
-    }
-    const sha = refRes.json.object.sha;
-    await request(`${repo.apiBase}/repos/${repo.owner}/${repo.repo}/git/refs`, {
-      method: "POST",
-      headers,
-      body: { ref: `refs/heads/${branch}`, sha },
-    });
-    let lastSha = sha;
-    for (const file of files) {
-      const put = await request(
-        `${repo.apiBase}/repos/${repo.owner}/${repo.repo}/contents/${file.path}`,
-        {
-          method: "PUT",
-          headers,
-          body: {
-            message,
-            content: file.contentBase64,
-            branch,
-          },
-        }
-      );
-      if (!put.ok) {
-        throw new Error(
-          `Falha ao escrever ${file.path} no GitHub (${put.status}): ${JSON.stringify(put.json)}`
-        );
-      }
-      lastSha = put.json.commit?.sha || lastSha;
-    }
-    return { sha: lastSha };
-  }
-
-  const form = new FormData();
-  form.set("branch", branch);
-  form.set("parents", startBranch);
-  form.set("message", message);
-  for (const file of files) {
-    const buf = Buffer.from(file.contentBase64, "base64");
-    form.set(file.path, new Blob([buf]));
-  }
-  const res = await fetch(`${repo.apiBase}/repositories/${repo.owner}/${repo.repo}/src`, {
-    method: "POST",
-    headers: { Authorization: `Bearer ${token}` },
-    body: form,
-  });
-  if (!res.ok) {
-    throw new Error(`Falha no commit Bitbucket (${res.status}): ${await res.text()}`);
-  }
-  return { sha: "ok" };
-}
-
 export async function createIssue(repoUrl, opts) {
   const { title, body, labels = ["bug"] } = opts;
   const repo = parseRepoUrl(repoUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jarvis-ai-framework",
-  "version": "3.2.0",
+  "version": "5.0.0",
   "description": "Jarvis framework",
   "type": "module",
   "bin": {
@@ -11,7 +11,7 @@
     "prepublishOnly": "echo 'Publishing jarvis-framework...'",
     "publish:gitlab": "npm publish",
     "test:comandos": "node test/comandos-docs.test.js",
-    "test:filtro": "node --test test/profile-filter.test.js test/token-report.test.js test/flow-map.test.js test/env-loader.test.js test/sync-engine.test.js test/vcs-api.test.js test/fetch-file.test.js test/publish-file.test.js",
+    "test:filtro": "node --test test/profile-filter.test.js test/token-report.test.js test/flow-map.test.js test/env-loader.test.js test/sync-engine.test.js test/vcs-api.test.js test/fetch-file.test.js test/publish-file.test.js test/docs-storage.test.js",
     "lint": "eslint bin/ test/",
     "lint:fix": "eslint bin/ test/ --fix",
     "format": "prettier --write bin/ test/",

package/rules/AGENTS.md

@@ -24,14 +24,16 @@ rules/                        # Sempre carregadas no início da sessão
     └── prod-rules.md    # Regras de especificacao
 
 rules-on-demand/              # Lidas pelo workflow que as usa (não carregadas no início)
-└── engineering/
-    ├── eng.start-rules.md    # Regras para /eng.start
-    ├── eng.plan-rules.md     # Regras para /eng.plan
-    ├── eng.work-rules.md     # Regras para /eng.work
-    ├── eng.pre-pr-rules.md   # Regras para /eng.pre-pr
-    ├── eng.pr-rules.md       # Regras para /eng.pr
-    ├── eng.tech-spec-rules.md # Regras para tech specs
-    └── eng.breakdown-subtasks-rules.md # Regras para o breakdown de subtarefas
+├── engineering/
+│   ├── eng.start-rules.md    # Regras para /eng.start
+│   ├── eng.plan-rules.md     # Regras para /eng.plan
+│   ├── eng.work-rules.md     # Regras para /eng.work
+│   ├── eng.pre-pr-rules.md   # Regras para /eng.pre-pr
+│   ├── eng.pr-rules.md       # Regras para /eng.pr
+│   ├── eng.tech-spec-rules.md # Regras para tech specs
+│   └── eng.breakdown-subtasks-rules.md # Regras para o breakdown de subtarefas
+└── product/
+    └── prod.guided-rules.md  # Modo Developer-Guided (lida só com PROD_MODE=developer-guided)
 ```
 
 ### `rules/` x `rules-on-demand/`
@@ -46,7 +48,8 @@ O Claude Code carrega tudo de `.claude/rules/` no início da sessão: `rules/` f
 1. .windsurf/rules / .cursor/rules  (mais alta)
 2. rules/engineering/eng-rules.md
 3. rules-on-demand/engineering/eng.{comando}-rules.md
-4. rules/product/prod-rules.md (mais baixa)
+4. rules-on-demand/product/prod.guided-rules.md (só com PROD_MODE=developer-guided)
+5. rules/product/prod-rules.md (mais baixa)
 ```
 
 **Regra**: Regras mais especificas tem precedencia sobre regras gerais.

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

@@ -9,7 +9,8 @@ O Jarvis não assume Jira, GitLab ou Slack. Leia `$IDE/ENV.md` e despache pelo a
 | Variável | Vendors | Adapter |
 |----------|---------|---------|
 | `TASK_MANAGER` | jira, linear, github, asana | `jarvis tasks comment` |
-| `VERSION_CONTROL` | gitlab, github, bitbucket | `jarvis vcs create-merge` / `create-issue` / `fetch-raw` |
+| `VERSION_CONTROL` | gitlab, github, bitbucket | `jarvis vcs create-merge` / `create-issue` |
+| `CENTRAL_DOCS_STORAGE` | filesystem (s3 e gdrive no futuro) | `jarvis docs fetch` / `sync` / `publish` |
 | `MESSAGE_COMUNICATOR` | slack, discord, teams | runtime `communicator/` |
 
 `{TASK_MANAGER_KEY}` = id da tarefa. Com board, é o id do card. Sem board, é o número de controle do usuário.
@@ -36,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

@@ -22,7 +22,6 @@ IMPORTANTE: Para que você funcione como o previsto e tenha todas as informaçõ
   - `PROD_FLOWS`
   - `PROD_TEMPLATES`
   - `PROD_DOCS`
-  - `CENTRAL_DOCS_REPO`
 - **Se o ENV.md não existir ou estiver incompleto**, o agente deve:
   1. Interromper a execução do comando solicitado
   2. Informar ao usuário que não podemos avançar sem o ENV.md. Mensagem abaixo.
@@ -40,21 +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
-CENTRAL_DOCS_REPO=[USER:LOCAL_CENTRAL_DOCS_REPO]
+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.
+- $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_REPO é o caminho para a pasta local que contém as especificações de produto centralizadas. Essa pasta é usada para manter um índice global de todas as especificações de produto.
+- $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
@@ -116,7 +114,8 @@ Em itens e especificações, utilizamos status para identificar quais etapas do
 - backlog: Item já foi estudado, sabemos o que fazer e está aguardando priorização de implementação.
 - in_progress: Item que está em desenvolvimento.
 - in_production: Item que está em produção.
-- cancelled: Item que foi descontinuado ou cancelado.
+- cancelled: Item cancelado antes de ser entregue.
+- deprecated: Item que esteve em produção e foi descontinuado.
 
 
 ## Padrão de nomes e pastas