trackfw 3.0.0 → 4.0.0

package/src/generators/init.js

@@ -13,6 +13,7 @@ const GOV_DIRS = [
   'docs/roadmaps/blocked',
   'docs/roadmaps/done',
   'docs/roadmaps/abandoned',
+  'vault/notes',
 ]
 
 const GLOBAL_ADRS_DIRECTIVE = 'Obrigatório: Inspecione e respeite todos os ADRs globais nos diretórios listados em adr_dirs (inclusive caminhos ~/...) antes de propor alterações de arquitetura.'
@@ -28,6 +29,7 @@ async function scaffold(cfg, cwd) {
     console.log(`  ✓ ${dir}`)
   }
 
+  generateVaultIndex(root)
   writeTrackfwConfig(cfg, root)
   generateValidateScript(cfg, root)
   generateAttentionScripts(cfg, root)
@@ -40,6 +42,29 @@ async function scaffold(cfg, cwd) {
   injectHooksDetected(root)
 }
 
+/**
+ * generateVaultIndex — cria vault/notes/index.md se ainda não existir.
+ * @param {string} root
+ */
+function generateVaultIndex(root) {
+  const indexPath = path.join(root || process.cwd(), 'vault', 'notes', 'index.md')
+  if (fs.existsSync(indexPath)) return
+  const content = `# Vault de Conhecimento
+
+> Ponto de entrada de conhecimento do projeto para agentes e pessoas.
+> Cada nota documenta uma causa-raiz, decisão técnica ou restrição não óbvia.
+> Crie notas com: trackfw note new "<título>"
+
+## Índice
+
+<!-- As notas serão listadas abaixo. Exemplo:
+- [nome-da-nota-YYYY-MM-DD](nome-da-nota-YYYY-MM-DD.md)
+-->
+`
+  fs.writeFileSync(indexPath, content, 'utf8')
+  console.log('  ✓ vault/notes/index.md')
+}
+
 // ---------------------------------------------------------------------------
 // trackfw.yaml
 // ---------------------------------------------------------------------------
@@ -54,7 +79,7 @@ backend: ${cfg.backend || ''}
 backend_framework: ${cfg.backendFramework || ''}
 pkg_manager: ${cfg.pkgManager || ''}
 hooks: ${cfg.hooks || ''}
-ci: ${cfg.ci || ''}
+ci: ${cfg.ci || ''}${cfg.forge ? `\nforge: ${cfg.forge}` : ''}
 require_req_in_commit: ${cfg.requireReqInCommit ? 'true' : 'false'}
 
 # governance paths (edit to match your project structure)
@@ -76,13 +101,26 @@ roadmap_namespacing: flat
 // scripts/trackfw-validate.sh
 // ---------------------------------------------------------------------------
 
-function generateValidateScript(cfg) {
-  fs.mkdirSync('scripts', { recursive: true })
+// generateValidateScript — cwd is optional and defaults to process.cwd() so
+// existing callers (scaffold(), which always runs with process.cwd() already
+// at the project root) keep working unchanged. `trackfw update`'s
+// validate-script target passes cwd explicitly so this can be applied
+// against a --dry-run sandbox root without ever touching the real project
+// tree — this is the SAME canonical generator scaffold() uses for `init`,
+// not a separate copy (see npm/src/commands/discover.js's writeValidateScript,
+// which is a different, simpler generator used only by `discover`/legacy
+// paths and must never be reused here — that mismatch was the ML-6H
+// validate-script parity bug: init wrote the rich per-backend script,
+// `update` overwrote it with the static 3-line one, so idempotent re-runs
+// reported "updated" instead of "skipped").
+function generateValidateScript(cfg, cwd) {
+  const root = cwd || process.cwd()
+  fs.mkdirSync(path.join(root, 'scripts'), { recursive: true })
 
   const script = buildValidateScript(cfg)
-  const scriptPath = path.join('scripts', 'trackfw-validate.sh')
+  const scriptPath = path.join(root, 'scripts', 'trackfw-validate.sh')
   fs.writeFileSync(scriptPath, script, { encoding: 'utf8', mode: 0o755 })
-  console.log(`  ✓ ${scriptPath}`)
+  console.log(`  ✓ ${path.join('scripts', 'trackfw-validate.sh')}`)
 }
 
 function buildValidateScript(cfg) {
@@ -356,14 +394,19 @@ This project uses **trackfw** for AI-native delivery governance.
 Chain: \`ADR → REQ → ROADMAP\` · States: \`backlog / analyzing / wip / blocked / done / abandoned\`
 
 ### Agent Protocol
-1. **Before starting:** run \`trackfw context\` · read \`docs/agents-working-context.md\`
-2. **After finishing:** update \`docs/agents-working-context.md\` with what changed
-3. **Before PR:** \`trackfw validate\` must pass
-4. **ML lifecycle — mandatory:**
+1. **Before any implementation (mandatory):** create governance artifacts FIRST, then branch:
+   \`trackfw req new "title"\` → \`trackfw roadmap new "title"\` → \`trackfw roadmap move <name> wip\` → \`git checkout -b feat/<branch>\`
+   ❌ Never create a branch before REQ + ROADMAP are in wip/
+   ❌ Never defer REQ/ROADMAP creation to a future task — they are prerequisites, not deliverables
+   ✓ \`trackfw validate\` enforces this via \`branch_has_wip_roadmap\` rule (v2.7.0+)
+2. **Before starting:** run \`trackfw context\` · read \`docs/agents-working-context.md\`
+3. **After finishing:** update \`docs/agents-working-context.md\` with what changed
+4. **Before PR:** \`trackfw validate\` must pass
+5. **ML lifecycle — mandatory:**
    - Starting a ML: edit roadmap \`**Status:** ⬜ Pendente\` → \`**Status:** 🔄 Em andamento\` + commit.
    - Completing a ML: edit roadmap → \`**Status:** ✅ Concluído\` + include in ML commit.
    - Analyzing a roadmap: move from \`backlog/\` to \`analyzing/\`; to \`wip/\` only when coding starts.
-5. **${GLOBAL_ADRS_DIRECTIVE}**
+6. **${GLOBAL_ADRS_DIRECTIVE}**
 
 ### Attention Signal (when you need user input during a task)
 Write \`docs/roadmaps/.trackfw-attention.json\`:
@@ -386,6 +429,13 @@ Delete the file when resolved. Visible as a live banner in \`trackfw serve\`.
 - **Security wave:** include a red-team review wave in every feature roadmap
 - **Test coverage:** TDD for critical logic; min 60% (prototype) / 80% (production)
 - Use \`/trackfw:architect\` to define stack before the first REQ
+
+### Key Commands
+- \`trackfw context\` — current governance state (always run first)
+- \`trackfw status\` — all artifacts and states
+- \`trackfw validate\` — governance consistency check
+- \`trackfw roadmap move <name> <state>\` — transition roadmap state
+- \`trackfw serve\` — live Kanban board at http://localhost:4080
 ` + RULES_END
 }
 
@@ -504,7 +554,8 @@ function generateClaudeMD(cfg) {
   content += '| `/trackfw:roadmap <req>` | Generate AI roadmap from a REQ |\n'
   content += '| `/trackfw:move <name> <state>` | Move roadmap between states manually |\n'
   content += '| `/trackfw:validate` | Run governance validation |\n'
-  content += '| `/trackfw:status` | Check what is in flight |\n\n'
+  content += '| `/trackfw:status` | Check what is in flight |\n'
+  content += '| `/trackfw:barrier` | Run the wave-release checklist before liberating the next wave |\n\n'
 
   content += '## CLI commands (terminal / CI)\n\n'
   content += '| Command | When to use |\n'
@@ -585,6 +636,66 @@ function generateClaudeMD(cfg) {
       content += 'No CI gate configured.\n'
   }
 
+  // Harness sections — derived from project governance conventions
+  content += '\n## Branch strategy\n\n'
+  content += 'One active branch at a time. Name it `feat/<slug>`, `fix/<slug>` or `refactor/<slug>`. '
+  content += 'Before creating a new branch, verify no other is genuinely open: run `git fetch origin --prune`, '
+  content += 'then `git branch -r --no-merged origin/main`, then for each candidate `git diff origin/main <branch> --stat`. '
+  content += 'An empty diff means it was squash-merged — ignore it. '
+  content += 'Squash merges do not mark a branch as merged, so `--no-merged` alone is not evidence. '
+  content += 'If the branch is stale and the diff looks inflated by main\'s own evolution, '
+  content += 'compare only the files the branch itself touched since the merge base.\n\n'
+
+  content += '## Definition of done\n\n'
+  content += 'Green build and tests do not close a microbatch. '
+  content += 'It is done when the requirement and the roadmap sit in the correct state folder, '
+  content += 'their declared status matches that folder, the final validation is recorded with evidence, '
+  content += 'no duplicate copy remains in another state, and `trackfw validate` reports no violations.\n\n'
+
+  content += '## Requirement scope\n\n'
+  content += 'Every requirement must declare an explicit negative scope: what must not be implemented. '
+  content += 'Boundaries prevent an implementing agent from inventing work.\n\n'
+
+  content += '## State requirements\n\n'
+  content += '`blocked` requires a reason and an owner. '
+  content += '`abandoned` requires a reason and a successor. '
+  content += '`wip` must reflect work that is genuinely active; '
+  content += 'anything stalled moves to `blocked` or `abandoned` instead of rotting in `wip`.\n\n'
+
+  content += '## Roadmap format\n\n'
+  content += 'Organize work as waves of microbatches. '
+  content += 'A wave groups microbatches that can run in parallel; a barrier separates waves. '
+  content += 'Microbatches sharing any file — including generated trees and build outputs — must be sequential, '
+  content += 'and the reason is documented. '
+  content += 'Each microbatch declares exact files, exact actions, measurable acceptance criteria and exact validation commands, '
+  content += 'so that a small model can execute it without guessing.\n\n'
+
+  content += '## When governance is not required\n\n'
+  content += 'A closed list of exemptions: a typo or local variable rename; a documentation-only change; '
+  content += 'a configuration tweak with no runtime effect; a direct revert; '
+  content += 'answering a question or reviewing without changes. '
+  content += 'Additionally, when the user reports a concrete bug, fix it directly and do not open an architectural analysis for it. '
+  content += '**This section takes precedence over the general rule that requires a requirement and a roadmap.** '
+  content += 'Anything touching business logic, an API contract, a data schema, authentication or authorization, '
+  content += 'localization, or user-facing behavior always requires governance, regardless of how few files it touches.\n\n'
+
+  content += '## Production incidents\n\n'
+  content += 'Inspect the live environment before proposing a fix: real variables, active credentials, '
+  content += 'granted permissions, running processes. '
+  content += 'Confirm the root cause against real evidence, then implement the smallest fix. '
+  content += 'Never edit static configuration files as a response to a root cause that has not been confirmed in the running environment.\n\n'
+
+  content += '## Iterative prototyping\n\n'
+  content += 'For complex or uncertain user-facing work, validate the concept with a disposable, isolated prototype '
+  content += 'that the user reviews visually, and only then write the decision record and the production roadmap. '
+  content += 'Build and test success is not evidence that an interface is right.\n\n'
+
+  content += '## Autopilot\n\n'
+  content += 'Ask everything you need before starting. '
+  content += 'Once started, do not interrupt for confirmations that could have been anticipated. '
+  content += 'Decide low-risk details autonomously following existing project conventions, '
+  content += 'and record autonomous decisions in the commit message.\n'
+
   injectOrUpdateRules('CLAUDE.md', content)
   console.log('  ✓ CLAUDE.md')
 }
@@ -613,14 +724,20 @@ function backendCommands(cfg) {
 }
 
 // ---------------------------------------------------------------------------
-// .claude/commands/trackfw/ — 7 slash commands
+// .claude/commands/trackfw/ — slash commands
+//
+// CLAUDE_COMMANDS is the single source of truth for the set of slash
+// commands installed by trackfw. Both generateClaudeCommands (normal path,
+// idempotent — never overwrites an existing file) and
+// generateClaudeCommandsForce (force path — always overwrites) install
+// from this same map; they only differ in overwrite behavior. This mirrors
+// the Go CLI's installSkillsInner(force) and the Python CLI's single
+// generate_claude_commands — one list, one force flag. Do not fork this map
+// again: a prior divergence let the force path fall behind the normal path
+// (missing roadmap.md, implement.md, barrier.md) undetected.
 // ---------------------------------------------------------------------------
 
-function generateClaudeCommands() {
-  const dir = '.claude/commands/trackfw'
-  fs.mkdirSync(dir, { recursive: true })
-
-  const commands = {
+const CLAUDE_COMMANDS = {
     'adr.md': `Execute o seguinte comando bash: \`trackfw adr new "$ARGUMENTS"\`
 
 Se o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:
@@ -700,9 +817,16 @@ trackfw não está instalado. Instale com:
    Com base no conteúdo da REQ, gere um roadmap seguindo **estritamente** este formato:
 
    \`\`\`markdown
+   ---
+   status: backlog
+   date: <YYYY-MM-DD>
+   req: "docs/req/<arquivo-selecionado>.md"
+   squad: ""
+   ---
+
    # Roadmap: <título derivado da REQ>
 
-   > Criado em: <YYYY-MM-DD> | Status: ⬜ Backlog
+   > Created: <YYYY-MM-DD> | Status: backlog
 
    ## Diagnóstico / Contexto
    <resumo do problema, motivação e escopo extraídos da REQ>
@@ -720,6 +844,13 @@ trackfw não está instalado. Instale com:
    - [ ] build sem erros
    - [ ] testes verdes
    **Comandos de validação:** \`<comando de build e teste do projeto>\`
+
+   ### ML-1B — <título> (se independente de ML-1A)
+   ...
+
+   ## Wave 2 — <nome> (depende de Wave 1)
+   > Dependências: Wave 1 completa
+   ...
    \`\`\`
 
    **Princípios obrigatórios:**
@@ -732,10 +863,12 @@ trackfw não está instalado. Instale com:
 4. **Salvar o arquivo**
    - Calcule o slug: título em lowercase, espaços → hifens, remova caracteres especiais
    - Crie o arquivo em \`docs/roadmaps/backlog/ROADMAP-<YYYY-MM-DD>-<slug>.md\`
+   - Preencha \`req:\` com o caminho relativo completo da REQ selecionada
    - Use a data de hoje
 
 5. **Confirmar**
-   Informe o caminho do arquivo criado e um resumo das Waves e total de MLs gerados.`,
+   Informe o caminho do arquivo criado e um resumo das Waves e total de MLs gerados.
+`,
 
     'implement.md': `Você é o orquestrador de implementação do trackfw. Siga o fluxo abaixo **sem pular etapas**.
 
@@ -848,6 +981,51 @@ Roadmap: docs/roadmaps/done/<nome>.md
 Próximo passo: abrir PR com gh pr create
 \`\`\``,
 
+    'barrier.md': `Você é o \`trackfw_architect\`, a única autoridade Git deste projeto. Este comando executa o checklist operacional de liberação de uma wave — nenhum outro agente commita, faz push ou libera a próxima wave.
+
+## Argumento
+
+\`$ARGUMENTS\` no formato \`<roadmap> <wave>\`. Se ausente ou incompleto, pergunte ao usuário qual roadmap (em \`docs/roadmaps/wip/\`) e qual número de wave validar.
+
+---
+
+## Núcleo determinístico
+
+Execute primeiro:
+\`\`\`bash
+trackfw barrier <roadmap> --wave <n> --json
+\`\`\`
+
+Este comando é **necessário mas não suficiente**. Ele verifica MLs concluídos, evidências e \`trackfw validate\`, mas não substitui as inspeções especializadas nem a auditoria de diff abaixo — nenhuma delas é avaliada pelo binário. Consulte a seção \`trackfw barrier\` em \`docs/cli-parity.md\` para o contrato completo (estados, exit codes, saída JSON).
+
+Se o comando retornar exit code não-zero (\`blocked\` ou erro de resolução): pare, reporte a falha ao usuário e não prossiga no checklist até que a wave passe.
+
+---
+
+## Definição de pronto da barrier — checklist completo
+
+Antes de liberar a próxima wave, confirme cada item com evidência concreta — não presuma:
+
+1. **Todos os MLs da wave concluídos e marcados** — cada ML da wave está com \`**Status:** ✅ Concluído\` no roadmap.
+2. **Testes unitários e E2E aplicáveis executados** — rode os comandos de validação declarados em cada ML.
+3. **Build aplicável sem erros** — rode o comando de build do(s) workspace(s) afetado(s).
+4. **Cada critério de aceite inspecionado com evidência** — leia os arquivos modificados e confirme contra os critérios listados, não apenas contra os testes.
+5. **Agente code-quality reportou conformidade, performance, robustez e clareza** — invoque o agente \`code-quality\` quando a mudança introduzir lógica nova, duplicação relevante ou risco de manutenibilidade.
+6. **Agente security reportou SAST, privilégios, controle de acesso e camadas aplicáveis** — invoque o agente \`security\` quando a mudança tocar autenticação, segredos, entrada externa ou permissões.
+7. **Gates pré-commit declarados pelo projeto executados** — rode os hooks/gates configurados (lint, format, testes de contrato).
+8. **\`trackfw validate --json\` aprovado** — execute e confirme zero violações.
+9. **Diff auditado contra o escopo** — revise o diff completo; confirme que não há alterações de agentes concorrentes nem arquivos fora do escopo do ML (ex: \`docs/adr/\`, \`docs/req/\`, \`docs/roadmaps/\` quando não autorizado ao especialista).
+10. **Resultado registrado antes de liberar a próxima wave** — anote no roadmap ou na resposta ao usuário que a wave passou, com a evidência de cada item acima.
+
+Se qualquer item falhar: bloqueie a próxima wave, identifique o item e o agente responsável, e despache um microlote corretivo. Só repita o checklist depois que o corretivo for concluído.
+
+---
+
+## Autoridade Git
+
+Somente o \`trackfw_architect\` cria branch, audita diff, commita e faz push. Especialistas entregam trabalho sem commit — cabe a este papel revisar, commitar e sugerir a abertura de PR/MR (sem abrir automaticamente sem autorização do usuário).
+`,
+
     'architect.md': `Você é o guia de arquitetura do trackfw. Ajude o usuário a escolher a stack correta e arquitetar a aplicação em linguagem simples, acessível para times não técnicos.
 
 ## Passo 1 — Descoberta de Negócio
@@ -926,13 +1104,21 @@ Oriente o usuário:
 2. Gere o roadmap em microlotes com /trackfw:roadmap
 3. Inicie a implementação com /trackfw:implement
 \`\`\``,
-  }
+}
+
+/**
+ * installClaudeCommandsInner — fonte única de escrita dos slash commands.
+ * @param {string} dir diretório de destino (já resolvido)
+ * @param {boolean} force quando true, sobrescreve arquivos existentes
+ */
+function installClaudeCommandsInner(dir, force) {
+  fs.mkdirSync(dir, { recursive: true })
 
   let created = 0
   let skipped = 0
-  for (const [filename, content] of Object.entries(commands)) {
+  for (const [filename, content] of Object.entries(CLAUDE_COMMANDS)) {
     const filePath = path.join(dir, filename)
-    if (fs.existsSync(filePath)) {
+    if (!force && fs.existsSync(filePath)) {
       skipped++
       continue
     }
@@ -940,13 +1126,28 @@ Oriente o usuário:
     created++
   }
 
-  if (skipped > 0) {
+  if (force) {
+    console.log(`  ✓ ${dir} (${created} slash commands sobrescritos)`)
+  } else if (skipped > 0) {
     console.log(`  ✓ ${dir} (${created} slash commands criados, ${skipped} já existiam — não sobrescritos)`)
   } else {
     console.log(`  ✓ ${dir} (${created} slash commands)`)
   }
 }
 
+/**
+ * generateClaudeCommands — instala os slash commands de forma idempotente:
+ * nunca sobrescreve um arquivo já existente. Honra o `rootDir` recebido
+ * (mesma convenção do gêmeo forçado generateClaudeCommandsForce e do
+ * generate_claude_commands(cwd) do Python); quando omitido, cai no
+ * caminho relativo ao cwd do processo, preservando o comportamento
+ * histórico consumido pelos testes que chamam sem argumento.
+ */
+function generateClaudeCommands(rootDir) {
+  const dir = rootDir ? path.join(rootDir, '.claude', 'commands', 'trackfw') : '.claude/commands/trackfw'
+  installClaudeCommandsInner(dir, false)
+}
+
 // ---------------------------------------------------------------------------
 // AI tool installers
 // ---------------------------------------------------------------------------
@@ -1039,25 +1240,13 @@ async function installIntegrationTarget(target, cwd = process.cwd(), scope = 'pr
 }
 
 /**
- * generateClaudeCommandsForce — re-gera todos os slash commands, sobrescrevendo arquivos existentes.
+ * generateClaudeCommandsForce — re-gera todos os slash commands, sobrescrevendo
+ * arquivos existentes. Instala exatamente o mesmo conjunto de CLAUDE_COMMANDS
+ * usado por generateClaudeCommands — só o comportamento de sobrescrita difere.
  */
 function generateClaudeCommandsForce(rootDir) {
   const dir = rootDir ? path.join(rootDir, '.claude', 'commands', 'trackfw') : '.claude/commands/trackfw'
-  fs.mkdirSync(dir, { recursive: true })
-
-  const commands = {
-    'adr.md': `Execute o seguinte comando bash: \`trackfw adr new "$ARGUMENTS"\`\n\nSe o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:\n\n\`\`\`\ntrackfw não está instalado. Instale com uma das opções:\n\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n  npm install -g trackfw\n  pip install trackfw\n\`\`\``,
-    'req.md': `Execute o seguinte comando bash: \`trackfw req new "$ARGUMENTS"\`\n\nSe o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:\n\n\`\`\`\ntrackfw não está instalado. Instale com uma das opções:\n\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n  npm install -g trackfw\n  pip install trackfw\n\`\`\``,
-    'validate.md': `Execute o seguinte comando bash: \`trackfw validate\`\n\nSe o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:\n\n\`\`\`\ntrackfw não está instalado. Instale com uma das opções:\n\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n  npm install -g trackfw\n  pip install trackfw\n\`\`\``,
-    'status.md': `Execute o seguinte comando bash: \`trackfw status\`\n\nSe o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:\n\n\`\`\`\ntrackfw não está instalado. Instale com uma das opções:\n\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n  npm install -g trackfw\n  pip install trackfw\n\`\`\``,
-    'move.md': `Execute o seguinte comando bash: \`trackfw roadmap move $ARGUMENTS\`\n\nO formato esperado é: \`<nome-do-roadmap> <estado>\`\nEstados válidos: \`backlog\`, \`analyzing\`, \`wip\`, \`blocked\`, \`done\`, \`abandoned\`\n\nSe o comando falhar, instale trackfw com:\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh`,
-    'architect.md': `Você é o guia de arquitetura do trackfw. Ajude o usuário a escolher a stack correta e arquitetar a aplicação em linguagem simples, acessível para times não técnicos.\n\n## Passo 1 — Descoberta de Negócio\n\nFaça ao usuário as seguintes perguntas em linguagem simples, uma por vez:\n\n1. "O que sua aplicação vai fazer? Descreva em 2-3 frases como se fosse explicar para alguém de fora da TI."\n2. "Quantas pessoas vão usar esse sistema simultaneamente? (< 10 pessoas / 10-100 pessoas / > 100 pessoas)"\n3. "Esse sistema vai para produção de verdade ou é um protótipo para validar uma ideia?"\n4. "Você precisa de login/autenticação de usuários? (Sim / Não / Não sei)"\n5. "Tem alguma restrição de tecnologia ou preferência da empresa? (ex: só Java, só Microsoft, etc.)"\n\n---\n\n## Passo 2 — Recomendação de Stack\n\nCom base nas respostas, escolha **UM** dos combos pré-validados:\n\n### Combo A — Protótipo Rápido\n**Quando usar:** prototipagem, validação de ideia, até ~10 usuários, sem pressão de produção.\n- **Frontend:** React + Vite\n- **Backend:** FastAPI (Python) ou Express (Node.js)\n- **Banco:** SQLite + SQLAlchemy / Prisma\n- **Auth:** JWT simples quando necessário\n- **Docker:** Dockerfile básico para o backend\n\n### Combo B — Sistema Pequeno/Médio em Produção\n**Quando usar:** sistema real, 10-100 usuários, robustez e manutenibilidade.\n- **Frontend:** Next.js (SSR + rotas prontas)\n- **Backend:** FastAPI (Python) ou NestJS (Node.js)\n- **Banco:** PostgreSQL + ORM (SQLAlchemy / Prisma / TypeORM)\n- **Auth:** OAuth2 com JWT (Supabase Auth ou Auth0)\n- **Docker:** docker-compose com frontend + backend + banco\n\n### Combo C — Enterprise / Java\n**Quando usar:** integração com sistemas corporativos, > 100 usuários, exigência de Java.\n- **Frontend:** Angular\n- **Backend:** Spring Boot\n- **Banco:** PostgreSQL + Hibernate\n- **Auth:** Spring Security + OAuth2 (Keycloak ou Azure AD)\n- **Docker:** docker-compose com todos os serviços\n\nApresente o combo recomendado com explicação simples do motivo.\n\n---\n\n## Passo 3 — Arquitetura em Camadas (explicação simples)\n\nExplique a arquitetura com uma metáfora de negócio:\n\n"Pense na aplicação como um restaurante:\n- **Frontend** = o salão: o que o cliente vê e interage\n- **Backend** = a cozinha: onde as regras de negócio acontecem, nunca exposta diretamente\n- **Banco de dados** = a despensa: onde os dados ficam guardados, acessada só pela cozinha"\n\nReforce as **Architecture Directives** já injetadas no CLAUDE.md deste projeto: separação em 3 camadas sem dados em memória (sempre DB + ORM), auth + Docker + .env desde o dia 1, validação em 2 camadas, contrato OpenAPI antes de codar, wave de segurança em todo roadmap e cobertura mínima de testes (60% protótipo / 80% produção).\n\n---\n\n## Passo 4 — Gerar o ADR de Stack\n\nExecute \`/trackfw:adr\` com o título: \`"Stack e arquitetura em camadas — [nome do projeto]"\`\n\nO ADR deve registrar a stack escolhida (combo e componentes), motivação baseada nas respostas, alternativas descartadas e princípios de arquitetura adotados.\n\n---\n\n## Passo 5 — Próximos Passos\n\nOriente o usuário:\n\n\`\`\`\n✅ Stack definida. Próximos passos:\n\n1. Crie a REQ da primeira feature com /trackfw:req\n2. Gere o roadmap em microlotes com /trackfw:roadmap\n3. Inicie a implementação com /trackfw:implement\n\`\`\``,
-  }
-
-  for (const [filename, content] of Object.entries(commands)) {
-    fs.writeFileSync(path.join(dir, filename), content, 'utf8')
-  }
-  console.log(`  ✓ .claude/commands/trackfw/ (${Object.keys(commands).length} slash commands sobrescritos)`)
+  installClaudeCommandsInner(dir, true)
 }
 
 /**
@@ -1139,6 +1328,7 @@ module.exports = {
   generateClaudeMD,
   generateClaudeCommands,
   generateClaudeCommandsForce,
+  generateVaultIndex,
   installSkillsForce,
   installAgents,
   installGemini,

package/src/generators/note.js

@@ -0,0 +1,154 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { localDateISO } = require('./date')
+
+const VAULT_DIR = 'vault/notes'
+const INDEX_FILE = 'vault/notes/index.md'
+
+/**
+ * Converte título em slug kebab-case lowercase sem acentos.
+ * Reutiliza a mesma lógica do adr.js (toSlug).
+ * @param {string} s
+ * @returns {string}
+ */
+function toSlug(s) {
+  // NFKD normalization + remove combining marks (diacríticos) + lowercase + non-alphanumeric → hífen
+  return s
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/**
+ * Retorna a data LOCAL atual no formato YYYY-MM-DD.
+ * Delega para localDateISO() — usa getDate/getMonth/getFullYear (hora local),
+ * não toISOString (UTC).
+ * @returns {string}
+ */
+function today() {
+  return localDateISO()
+}
+
+/**
+ * Cria uma nova nota em vault/notes/<slug>-YYYY-MM-DD.md e linka no index.md.
+ * Idempotente: falha com erro claro se a nota já existir.
+ * @param {string} title
+ * @param {string} [cwd]
+ */
+function newNote(title, cwd) {
+  const root = cwd || process.cwd()
+  const vaultDir = path.join(root, VAULT_DIR)
+  fs.mkdirSync(vaultDir, { recursive: true })
+
+  const slug = toSlug(title)
+  const date = today()
+  const filename = `${slug}-${date}.md`
+  const notePath = path.join(vaultDir, filename)
+
+  if (fs.existsSync(notePath)) {
+    throw new Error(`nota "${filename}" já existe — não sobrescrita`)
+  }
+
+  const body = `---
+title: "${title}"
+tags: []
+date: ${date}
+related: []
+---
+
+# ${title}
+
+## Problem
+
+<!-- Descreva o problema ou situação que motivou esta nota. -->
+
+## Root cause
+
+<!-- Qual foi a causa raiz identificada? -->
+
+## Solution
+
+<!-- Como foi resolvido ou mitigado? O que deve ser feito? -->
+`
+
+  fs.writeFileSync(notePath, body, 'utf8')
+  appendNoteToIndex(filename, root)
+  console.log(`created ${path.join(VAULT_DIR, filename)}`)
+}
+
+/**
+ * Acrescenta link para filename no vault/notes/index.md.
+ * Cria o index.md se não existir. Não duplica se já estiver linkado.
+ * @param {string} filename
+ * @param {string} [cwd]
+ */
+function appendNoteToIndex(filename, cwd) {
+  const root = cwd || process.cwd()
+  const indexPath = path.join(root, INDEX_FILE)
+
+  if (!fs.existsSync(indexPath)) {
+    const initial = `# Vault de Conhecimento
+
+> Ponto de entrada de conhecimento do projeto para agentes e pessoas.
+
+## Índice
+
+`
+    fs.writeFileSync(indexPath, initial, 'utf8')
+  }
+
+  const content = fs.readFileSync(indexPath, 'utf8')
+  const nameWithoutExt = filename.replace(/\.md$/, '')
+
+  // Verifica se já linkado (link markdown ou wikilink)
+  if (
+    content.includes(`(${filename})`) ||
+    content.includes(`[[${nameWithoutExt}]]`) ||
+    content.includes(`[[${filename}]]`)
+  ) {
+    return
+  }
+
+  const link = `- [${nameWithoutExt}](${filename})\n`
+  fs.appendFileSync(indexPath, link, 'utf8')
+}
+
+/**
+ * Retorna todos os arquivos .md em vault/notes/ exceto index.md.
+ * Retorna [] se o diretório não existir.
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+function noteFiles(cwd) {
+  const root = cwd || process.cwd()
+  const vaultDir = path.join(root, VAULT_DIR)
+  if (!fs.existsSync(vaultDir)) return []
+  return fs
+    .readdirSync(vaultDir)
+    .filter((f) => f.endsWith('.md') && f !== 'index.md')
+}
+
+/**
+ * Retorna true se o index.md referencia filename.
+ * @param {string} filename
+ * @param {string} [cwd]
+ * @returns {boolean}
+ */
+function indexContains(filename, cwd) {
+  const root = cwd || process.cwd()
+  const indexPath = path.join(root, INDEX_FILE)
+  if (!fs.existsSync(indexPath)) return false
+  const content = fs.readFileSync(indexPath, 'utf8')
+  const nameWithoutExt = filename.replace(/\.md$/, '')
+  return (
+    content.includes(`(${filename})`) ||
+    content.includes(`[[${nameWithoutExt}]]`) ||
+    content.includes(`[[${filename}]]`)
+  )
+}
+
+module.exports = { newNote, appendNoteToIndex, noteFiles, indexContains, toSlug, today }