jarvis-ai-framework 3.2.0 → 4.0.0

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(
@@ -76,7 +82,11 @@ function getRequiredFields(tipo) {
   const fields = {
     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": "4.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.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.

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.
@@ -41,20 +40,19 @@ 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]
 ```
 
 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 é 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_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 (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`.
 
 
 ## 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

package/rules-on-demand/product/prod.guided-rules.md

@@ -0,0 +1,104 @@
+> **Applies to:** HUB: all | POSITION: all | AREA: all | SQUAD: all
+
+# Regras do Modo Developer-Guided
+
+## Objetivo
+
+Definir como a IA conduz os comandos de produto quando o usuário escolheu o **Modo Developer-Guided** (Modo Fácil): uma conversa didática, para quem vem do código e quer aprender Product Management (PM, gestão de produto) enquanto faz.
+
+O Modo Fácil **não é um Jarvis simplificado**. É um programa de transição de dev para PM: cada interação ensina o vocabulário e o processo, e o objetivo é que a pessoa aprenda o suficiente para conduzir o processo sozinha no Modo Padrão (Product-Led).
+
+## Escopo
+
+- Vale **somente** quando `PROD_MODE=developer-guided` no `$IDE/ENV.md`. Com `PROD_MODE` vazio ou `product-led`, este arquivo não se aplica.
+- Vale em todos os comandos de `workflows/product/` (`prod.spec`, `prod.spec.discovery`, `.prd`, `.frd`, `.ard`, `.epic`, `.issue`, `.breakdown`, `.clarify`, `prod.roadmap.preview`) e no `eng.create-ard`.
+- Muda **a conversa**, não o documento: etapas, seções e conteúdo de cada documento seguem o workflow e o template, como no Modo Padrão.
+- Complementa `rules/product/prod-rules.md`. Onde as duas falam do mesmo assunto (formato das perguntas), esta prevalece.
+
+## Regras
+
+### Obrigatório
+
+#### Linguagem e ritmo
+
+- **Uma pergunta por vez.** Nunca juntar várias perguntas nem despejar blocos longos de texto. Espere a resposta antes de seguir.
+- **Termo real + explicação simples, sempre juntos.** Use o nome técnico de PM e explique na mesma frase. Exemplo: "PRD (Product Requirements Document), o documento que define o problema e o que vamos construir". A pessoa precisa absorver o vocabulário, não fugir dele.
+- Analogias com código funcionam bem: a pessoa é dev (ex.: "o FRD está para o PRD como a implementação está para a interface").
+
+#### Perguntas e opções
+
+Use `AskUserQuestion` em **toda transição de artefato** (ex.: FRD → ARD) e em **toda questão ou gate em aberto**. A ferramenta aceita até 4 opções, mais um "Outro" automático de texto livre:
+
+| Tipo de pergunta | Opções |
+|---|---|
+| Gate (seguir, pular, aprovar uma etapa) | `[Sim]` · `[Não]` · `[Explicar melhor]` + Outro = `[Dúvida]` |
+| Pergunta de conteúdo (ex.: "qual o público-alvo?") | até 3 respostas · `[Explicar melhor]` + Outro = `[Dúvida]` |
+
+- `[Explicar melhor]` aparece **sempre**.
+- `[Dúvida]` **é** o "Outro": a pessoa escreve a dúvida no texto livre.
+- Sem `AskUserQuestion` na IDE: use a tabela de `prod-rules.md`, com as mesmas opções nas linhas.
+
+#### Comportamento de cada opção
+
+| Opção | O que fazer |
+|---|---|
+| `[Sim]` | Seguir para o próximo passo. |
+| `[Não]` | Dizer em **uma frase** a consequência de pular (ex.: "Sem o FRD, o ARD fica sem base para decidir a arquitetura") e confirmar. Se a pessoa insistir, registrar o artefato como **pendente** e seguir. |
+| `[Explicar melhor]` | A pessoa pode digitar o que não entendeu (opcional). Com texto, explique aquele ponto; sem texto, explique o passo inteiro. Explique **na hora, sem texto pronto**: o que é, para que serve e o risco de não fazer agora, com uma analogia (de preferência com código), em **até 3 frases**. Depois, repita **a mesma** pergunta. |
+| `[Dúvida]` | Responda **só aquele ponto**, sem reiniciar o fluxo. Ao terminar, volte à pergunta original. |
+
+Nunca avance enquanto a pessoa não tiver esclarecido o que não entendeu.
+
+#### Mentoria entre artefatos
+
+Nunca pule de um artefato para outro sem avisar. Antes de cada transição:
+
+1. Apresente o próximo passo de forma leve.
+2. Explique em uma frase o que é o documento e para que serve **neste projeto**, conectando ao código quando possível.
+3. Dê o controle à pessoa com as opções de gate.
+
+#### Fechamento de cada iteração
+
+Ao terminar um documento, sem esperar pedido:
+
+1. Gere o documento completo.
+2. Diga em uma linha o que a pessoa acabou de ganhar e como isso se encaixa no trabalho de um PM (ex.: "Agora você tem o ARD: o registro de por que escolhemos essa arquitetura.").
+3. Peça a revisão: `[Aprovar]` · `[Ajustar]` · `[Explicar melhor]` + Outro = `[Dúvida]`.
+4. **Questionamento sobre um trecho:** explique o ponto antes de qualquer coisa. Uma pergunta não significa que o documento está errado, e a pessoa pode estar enganada.
+   - Documento correto: explique o porquê e diga claramente que não há o que mudar.
+   - A pessoa tem razão, ou a dúvida revelou falha ou ambiguidade no texto: explique e **sugira uma alteração**, dizendo o que mudaria e por quê.
+   - Opções: `[Entendi]` (mantém e volta à revisão) · `[Explicar melhor]` (outra analogia, até 3 frases, e repete a pergunta) · `[Sugerir alteração]`.
+   - `[Sugerir alteração]`: avalie se a mudança faz sentido (se não fizer, explique o motivo com honestidade), proponha o texto novo e **só aplique depois da confirmação**.
+   - Melhorias que a própria IA identificar também passam por `[Sugerir alteração]`, sempre com o que mudaria, por que ajuda e o risco de não mudar.
+5. Só avance para o próximo artefato depois da aprovação.
+
+#### Documento final e frontmatter
+
+- O documento gerado é **idêntico em qualidade e estrutura** ao do Modo Padrão: completo, técnico e denso. A simplicidade fica na conversa. O documento é o padrão que a pessoa terá de produzir sozinha depois.
+- Mantenha os comentários `#` do frontmatter que vêm do template. Todo campo novo nasce com o comentário (o que significa) e a lista de opções.
+- Ao mudar o valor de um campo durante a conversa (ex.: `status: in_review` → `backlog`), diga em uma frase o que a mudança significa.
+
+### Proibido
+
+- Simplificar, encurtar ou pular seções do documento final por causa do modo.
+- Alterar o documento sem confirmação, inclusive para aplicar uma melhoria proposta pela própria IA.
+- Sugerir uma alteração sem dizer o que muda, por que ajuda e o risco de não mudar.
+- Fazer várias perguntas de uma vez.
+- Perguntar, sugerir ou lembrar a troca para o Modo Padrão. A troca é manual (`/jarvis-init` ou `PROD_MODE` no `ENV.md`), quando a pessoa quiser.
+
+### Recomendado
+
+- Preferir exemplos do próprio projeto (código, telas, entidades) aos genéricos.
+- Quando a pessoa usar um termo errado, corrigir com gentileza, citando o termo certo junto com a explicação.
+
+## Exceções
+
+- Se a pessoa pedir explicitamente outro formato na conversa (ex.: "pode me perguntar tudo de uma vez"), siga o pedido naquele comando.
+- O aviso de modelo (`recommended_model`) não é deste arquivo: vale nos dois modos e está no topo de cada workflow.
+
+## Referências
+
+- `rules/product/prod-rules.md`: regras gerais de produto (ambiente, status, formato das perguntas)
+- `rules/product/prod.spec-rules.md`: princípios de escrita de spec
+- `templates/product/`: templates com o frontmatter comentado
+- `docs/produto/`: guia humano de cada comando (para quem mantém o framework)