jarvis-ai-framework 6.0.0 → 6.1.0

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

@@ -42,7 +42,7 @@ Por isso o texto tem de ser **completo, autossuficiente e sem ambiguidade**.
 
 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).
+3. Documentos de trabalho em `$PROD_DOCS` e `$ENG_DOCS` ligados à tarefa (PRD, FRD, épicos, histórias, ARD, RFC, SPEC, 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.

package/bin/README.md

@@ -24,7 +24,7 @@ bin/
     ├── 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 pelo adaptador + validação de frontmatter
-    │   ├── validate-frontmatter.js  # Valida/extrai frontmatter (PRD, FRD, épico, história, tarefa, ARD, RFC)
+    │   ├── validate-frontmatter.js  # Valida/extrai frontmatter (feature, delivery e documentos de trabalho: PRD, FRD, épico, história, tarefa, ARD, RFC, QA)
     │   ├── 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

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

@@ -3,7 +3,7 @@
  * (`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…)
+ * `{SQUAD}/engineering/{produto}/`). Documentos de trabalho (PRD, FRD, ARD, RFC, SPEC…)
  * não são publicados. O índice do squad é regenerado a cada publicação.
  * @module docs/publish-file
  */
@@ -28,6 +28,7 @@ export const WORKING_DOC_TYPES = Object.freeze([
   "task",
   "ard",
   "rfc",
+  "spec",
   "swagger",
   "qa-report",
 ]);

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

@@ -2,7 +2,8 @@ import { readFileSync } from 'node:fs'
 import { parseFrontmatter, extractFrontmatterBlock } from '../utils/frontmatter.js'
 
 /**
- * Valida frontmatter YAML de documentos (PRD, FRD, épico, história, tarefa, ARD, RFC)
+ * Valida frontmatter YAML da consolidação do Central docs (feature, delivery) e de documentos
+ * de trabalho (PRD, FRD, épico, história, tarefa, ARD, RFC, relatório de QA)
  * 
  * @param {string} filePath - Caminho do arquivo
  * @param {string} tipo - Tipo do documento (ver VALID_TYPES em publish-file.js)
@@ -55,10 +56,11 @@ export function validateFrontmatter(filePath, tipo) {
 
   // Validar status
   // Produto (rules/product/prod-rules.md), ARD (templates/engineering/ARD-template.md),
-  // discovery (prod-discovery-template.md) e RFC (RFC-template.md)
+  // discovery (prod-discovery-template.md), RFC (RFC-template.md) e
+  // SPEC (templates/engineering/ref-spec-template.md)
   const validStatuses = [
     'icebox', 'in_review', 'backlog', 'in_progress', 'in_production', 'cancelled', 'deprecated',
-    'proposed', 'approved',
+    'proposed', 'approved', 'superseded',
     'Draft', 'In Review', 'Ready for Decision', 'Accepted', 'Rejected', 'Superseded'
   ]
   

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jarvis-ai-framework",
-  "version": "6.0.0",
+  "version": "6.1.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/docs-storage.test.js test/env-upgrade.test.js test/docs-migrate.test.js test/init-upgrade.test.js test/workspace-mode.test.js test/stale-skills.test.js test/session-scan.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 test/env-upgrade.test.js test/docs-migrate.test.js test/init-upgrade.test.js test/workspace-mode.test.js test/stale-skills.test.js test/session-scan.test.js test/framework-refs.test.js test/validate-frontmatter.test.js",
     "lint": "eslint bin/ test/",
     "lint:fix": "eslint bin/ test/ --fix",
     "format": "prettier --write bin/ test/",

package/rules/artifact-style-rules.md

@@ -19,7 +19,7 @@ Esta rule só é copiada para `$IDE/rules/` quando o perfil tem `ARTIFACT_STYLE=
    - Esta rule **prevalece** sobre instruções de atribuição da IDE: não inclua `Co-Authored-By` de ferramenta nem "Generated with …".
    - Antes do push, o `eng.pr` confere e limpa o que a IDE tiver posto (Fase 3 do `eng.pr`).
 2. **Documento gerado: grava o padrão e pergunta.**
-   - Vale para todo `.md` que um comando grava, inclusive os de sessão: PRD, FRD, épico, história, discovery, ARD, RFC, tech spec, Central docs, `architecture.md`, `plan.md`, `daily.md` (e a linha de timesheet), `gate-checklist.md`.
+   - Vale para todo `.md` que um comando grava, inclusive os de sessão: PRD, FRD, épico, história, discovery, ARD, RFC, tech spec, SPEC, Central docs, `architecture.md`, `plan.md`, `daily.md` (e a linha de timesheet), `gate-checklist.md`.
    - **Exceção: `pull-request.md`.** Ele é o texto que vira o título e a descrição do PR/MR, então já é a versão pública (regra 1): nasce sem marcas e **não** recebe a pergunta nem um `.public.md`.
    - **Pergunte uma vez, no fim do comando**, depois de gravar o documento padrão (como hoje), com um `AskUserQuestion` de **várias perguntas em abas**, uma por documento: **"Quer a versão humanizada de {documento}?"** (**Não**, padrão / **Sim**). O limite é 4 abas por chamada; com mais documentos, divida em chamadas.
    - **No ciclo de engenharia** (`eng.start`, `eng.plan`, `eng.work`, `eng.pre-pr`), **não pergunte**: a pergunta única vem no fim do `eng.pr`, com uma aba para cada documento da sessão que existir (`architecture.md`, `plan.md`, `gate-checklist.md`, `daily.md`). Comandos que rodam isolados (`prod.*`, `eng.create-ard`, `eng.create-rfc` etc.) perguntam no próprio fim.

package/rules/engineering/eng-rules.md

@@ -65,7 +65,7 @@ env_file: "@/ENV.md"
   - No modo workspace a raiz (a pasta que contém `$IDE/`) **não é um repositório** e guarda itens fora do git (`.claude/`, `.jarvis/`, `.vscode/`, `node_modules/`). `grep`, `ls` e `Glob` na raiz leem tudo isso como se fosse código do projeto e confundem a análise.
   - **Código do projeto** = só as subpastas com `.git/` (ou as de `WORKSPACE_REPOS`, quando preenchido). Busque e leia código **dentro delas**.
   - **Ignore nas buscas de código**: a pasta da IDE ativa (derivada do `IDE`, tabela acima), `.jarvis/`, `.vscode/`, `node_modules/` e o `CDD-MIND-MAP.md`. Leia esses itens **só quando o workflow mandar** (ENV.md, rules, skills, templates, sessão).
-  - **`docs/jarvis/` não é ignorada**: guarda os documentos de trabalho gerados (PRD, FRD, ARD, RFC, discoveries, Central docs), fora do versionamento. Leia-a sob demanda, como documento de trabalho, e não como código.
+  - **`docs/jarvis/` não é ignorada**: guarda os documentos de trabalho gerados (PRD, FRD, ARD, RFC, SPEC, discoveries, Central docs), fora do versionamento. Leia-a sob demanda, como documento de trabalho, e não como código.
   - **Pastas de outras IDEs** nunca são lidas (vale o "Isolamento de IDE" acima).
   - Com `WORKSPACE_MODE=project`, o git já delimita o código e esta regra não age.
 
@@ -241,6 +241,6 @@ Ao orientar o usuário sobre a movimentação de cards no board (Jira, GitLab, L
 | `pleno` | Média - explicar decisões não-óbvias |
 | `senior` | Alta - executar e reportar decisões |
 | `staff`, `tech-lead` | Muito alta - consultar apenas em trade-offs críticos |
-| `generalist` | Muito alta - consultar apenas em trade-offs críticos (superusuário: acumula funções de outras posições) |
+| `generalist` | Muito alta - consultar apenas em trade-offs críticos (superusuário: acumula funções de outras posições; satisfaz qualquer gate por POSITION, ver taxonomy.md) |
 
 > ⚠️ **Escape Hatch**: O usuário pode sempre override qualquer regra contextual com instrução explícita.

package/rules/product/prod-rules.md

@@ -54,7 +54,7 @@ Abaixo, segue uma descrição de algumas das variáveis mais importantes para as
 - $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: 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`.
+- $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, SPEC) 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.tech-spec-rules.md

@@ -17,6 +17,21 @@ env_file: "@/ENV.md"
 
 ---
 
+## Modos
+
+O `/eng.build-tech-spec` tem dois modos, escolhidos na triagem do workflow:
+
+| Modo | Quando usar | O que gera | Detalhe |
+|------|-------------|------------|---------|
+| **Delivery Spec** | Há card de origem (épico ou história) | Tech Spec arquitetural (épico) ou de implementação com subtarefas (história), na sessão do card | `$IDE/skills/eng-global-tech-spec/references/delivery-spec.md` |
+| **Reference Spec** | Documento normativo sem card: contrato, convenção de nome, topologia, perfil de spec, fases de adoção | Especificação técnica de referência em `$ENG_DOCS/SPEC/SPEC-###-{slug}.md` (template `ref-spec-template.md`) | `$IDE/skills/eng-global-tech-spec/references/reference-spec.md` |
+
+- O **Reference Spec** não exige card e **não** quebra em subtarefas: a regra das subtarefas de 4h a 1 dia, a integração com o board e a seção "Localização" abaixo valem só para o Delivery Spec.
+- No Reference Spec, cada decisão resolvida aponta a origem (RFC-xxx, ARD-xxx ou "resolvida aqui"), e a checagem de RFC sem origem usa 7 dos 8 critérios (sai "padrão reutilizável", que é a natureza do documento).
+- A spec de referência é documento de trabalho, numerada como RFC e ARD (maior `SPEC-###` existente + 1, senão `001`) e **não** é publicada no Central docs.
+
+---
+
 ## Localização de Arquivos
 
 > **NOTA**: Tech specs NÃO são salvas em `master-docs/`. São salvas na sessão do projeto e anexadas no Jira.
@@ -31,14 +46,15 @@ Sempre siga as instruções de acordo com as relações abaixo:
 
 ### Workflows de Tech Spec
 
-- **import `$IDE/workflows/engineering/eng.build-tech-spec.md`**: Criação de tech spec a partir de história do Jira
-- **import `$IDE/workflows/engineering/eng.breakdown-subtasks.md`**: Quebra de tech spec em subtarefas executáveis
+- **import `$IDE/workflows/engineering/eng.build-tech-spec.md`**: Criação de tech spec a partir de um card (épico ou história) ou de uma especificação técnica de referência; no Delivery Spec, já quebra a história em fatias verticais de 4h a 1 dia
+- **import `$IDE/workflows/engineering/eng.breakdown-subtasks.md`**: Detalhamento opcional das fatias de uma tech spec pronta como passo a passo para outra pessoa executar sem perguntar (não gera a spec)
 - **import `$IDE/workflows/engineering/eng.start.md`**: Início de desenvolvimento de feature (referência)
 - **import `$IDE/workflows/engineering/eng.plan.md`**: Planejamento de execução (referência)
 
 ### Templates
 
-- **import `$IDE/templates/engineering/tech-spec-template.md`**: Template completo de tech spec
+- **import `$IDE/templates/engineering/tech-spec-template.md`**: Template completo de tech spec (Delivery Spec)
+- **import `$IDE/templates/engineering/ref-spec-template.md`**: Template da especificação técnica de referência (Reference Spec)
 
 ### Regras
 
@@ -74,7 +90,7 @@ $SESSION_FOLDER/{TASK_MANAGER_KEY}/tech-spec.md
 ### Nomenclatura
 
 - **Formato da pasta**: `{jira-key}` em **lowercase** (ex: `TASK-123` → `task-123`)
-- **Arquivo**: Sempre `tech-spec.md` ou `architecture.md`
+- **Arquivo**: `tech-spec.md` (história), `tech-spec-arch.md` (épico) ou `architecture.md`
 - **Exemplo**: `$SESSIONS_DIR/eng/task-123/tech-spec.md`
 
 > ⚠️ **IMPORTANTE**: NÃO adicione descrições ou sufixos ao nome da pasta.

package/skills/AGENTS.md

@@ -22,6 +22,9 @@ skills/
 ├── eng-global-investigation/    # Método de investigação de bugs (causa raiz, hipóteses, veredito, política de acesso); usado pelo /eng.debug
 │   ├── SKILL.md
 │   └── references/
+├── eng-global-tech-spec/        # Método do /eng.build-tech-spec: Delivery Spec (épico/história) e Reference Spec
+│   ├── SKILL.md
+│   └── references/
 ├── eng-global-pr/               # Criacao de Pull/Merge Requests (GitLab/GitHub/Bitbucket)
 │   └── SKILL.md
 ├── eng-global-task-comment/     # Comentário no card (Jira/Linear/GitHub Issues/Asana)
@@ -231,6 +234,7 @@ Skills são invocados de formas diferentes dependendo da IDE:
 | `/eng.pre-pr` | `eng-qa-planner`, `eng-global-docs-write`, `jarvis-docs-central` (detectar docs) |
 | `/eng.pr` | `eng-global-pr` |
 | `/eng.debug` (investigar um bug ou varrer um escopo) | `eng-global-investigation` |
+| `/eng.build-tech-spec` (Delivery Spec ou Reference Spec) | `eng-global-tech-spec` |
 | Comentário no card | `eng-global-task-comment` |
 | `jarvis docs sync` | `jarvis-docs-central` |
 | `jarvis docs publish` | `jarvis-docs-central` |

package/skills/eng-global-tech-spec/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: eng-global-tech-spec
+description: >
+  Método de especificação técnica do /eng.build-tech-spec, em dois modos: Delivery Spec (Tech Spec a
+  partir de um épico ou de uma história, com subtarefas de 4h a 1 dia para a história) e Reference
+  Spec (especificação técnica normativa, sem card e sem subtarefas: contratos, convenções, perfis
+  de spec). Cada modo tem o seu arquivo em references/, lido só quando o modo é escolhido.
+  Trigger: Use ao escrever uma Delivery Spec (Tech Spec a partir de um card) ou uma Reference Spec (spec técnica de referência).
+allowed-tools: Read Grep Glob Bash
+license: AGPL-3.0
+metadata:
+  author: jarvis-team
+  version: "1.0"
+  area: global
+---
+
+# eng-global-tech-spec
+
+Método para escrever especificações técnicas no Jarvis. O `/eng.build-tech-spec` faz o gate de cargo, a triagem de modo e a carga das especializações; esta skill traz o "como" de cada modo e as regras que valem nos dois.
+
+## Modos
+
+Leia **só** o arquivo do modo escolhido pelo workflow:
+
+| Modo | Quando | Arquivo | Saída |
+|------|--------|---------|-------|
+| Delivery Spec | Há card de origem (épico ou história) | [references/delivery-spec.md](references/delivery-spec.md) | `$SESSIONS_DIR/eng/{card}/tech-spec-arch.md` (épico) ou `tech-spec.md` com subtarefas (história) |
+| Reference Spec | Documento normativo sem card: contrato, convenção de nome, topologia, perfil de adaptação de uma spec, fases de implementação | [references/reference-spec.md](references/reference-spec.md) | `$ENG_DOCS/SPEC/SPEC-###-{slug}.md` (template `ref-spec-template.md`), sem subtarefas |
+
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| Delivery Spec › Fase 1.5 (necessidade de RFC) | `/eng.create-rfc` | Se a Tech Spec atender aos critérios que exigem RFC e o usuário escolher "A: Criar uma RFC agora" |
+| Delivery Spec › Caminho A › 2A.2 | `/jarvis-docs-central` | Se `CENTRAL_DOCS_STORAGE` estiver configurado |
+| Reference Spec › 2. Checagem de RFC | `/eng.create-rfc` | Sem RFC/ARD de origem, com algum dos 7 critérios "Sim" e a escolha "A: Criar uma RFC agora" |
+
+> As mesmas chamadas estão na tabela do workflow `eng.build-tech-spec`, com as do gate e das áreas.
+
+---
+
+## Regras Importantes
+
+### ⚠️ Nunca Assuma - Sempre Pergunte
+
+- Se informação crítica está faltando → **pergunte ao usuário**
+- Se há múltiplas interpretações possíveis → **peça clarificação**
+- Se decisão arquitetural tem trade-offs → **discuta com usuário**
+
+### 🎯 Foco em Valor Testável
+
+- Cada subtarefa deve entregar algo **testável e validável**
+- Evite subtarefas genéricas como "Implementar backend"
+- Prefira subtarefas específicas como "Criar endpoint POST /api/users com validação"
+
+### 📏 Estimativas Realistas
+
+- Subtarefas devem ter **entre 4 horas e 1 dia cada**, como fatias verticais completas
+- Se maior que 1 dia → **dividir em duas fatias verticais independentes** (nunca em camadas)
+- Se menor que 4h → **agrupar com a próxima** até formar uma fatia vertical completa
+- Incluir tempo para testes e documentação
+
+### 🔗 Rastreabilidade
+
+- Toda decisão deve ter **justificativa documentada**
+- Links entre documentos devem **funcionar**
+- Referências externas devem ser **específicas** (não "veja a documentação")
+
+### 🏗️ Seguir Convenções do Projeto
+
+- Analisar código existente antes de propor novos padrões
+- Manter **consistência** com arquitetura atual
+- Justificar **qualquer desvio** de padrões estabelecidos
+
+### 📐 Princípios de Documentação
+
+- **Valor do Usuário**: Sempre explicar o "porquê"
+- **Contexto Completo**: Documento deve ser auto-contido
+- **Terminologia Consistente**: Usar mesmos termos em toda documentação
+- **Critérios Testáveis**: Evitar linguagem vaga ("rápido", "fácil")
+
+
+---
+
+## Boas Práticas
+
+✅ **Fazer:**
+
+- Usar diagramas Mermaid para comunicar arquitetura
+- Documentar "por que" das decisões, não só "o que"
+- Quebrar em incrementos pequenos e testáveis
+- Validar com usuário em cada fase crítica
+- Manter rastreabilidade (links, referências)
+
+❌ **Evitar:**
+
+- Assumir requisitos não explícitos
+- Criar subtarefas maiores que 1 dia ou fatias horizontais (só enum, só repository, só DTO)
+- Pular análise de riscos
+- Propor tecnologias sem justificativa
+- Documentação vaga ou genérica
+