trackfw 2.10.0 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "CLI de governança para entrega de software: ADR → REQ → ROADMAP → kanban. Suporte nativo a agentes de IA (Claude Code, Gemini CLI, Cursor).",
   "keywords": [
     "cli",

package/src/commands/discover.js

@@ -211,11 +211,32 @@ function installHook(framework, rootDir) {
     if (fs.existsSync(pkgJson)) {
       installHusky(rootDir);
     } else {
+      // Node.js disponível mas sem package.json → husky via npx
+      try {
+        execSync('node --version', { stdio: 'pipe' });
+        installHuskyNPX(rootDir);
+        return;
+      } catch (_) {}
+      // fallback: lefthook
       installLefthook(rootDir);
     }
   }
 }
 
+function installHuskyNPX(rootDir) {
+  console.log('ℹ node detected — using husky via npx (no package.json required)');
+  try {
+    execSync('npx husky init', { cwd: rootDir, stdio: 'inherit' });
+  } catch (_) {
+    console.log('⚠ npx husky init failed — install manually: npx husky init');
+  }
+  const huskyDir = path.join(rootDir, '.husky');
+  fs.mkdirSync(huskyDir, { recursive: true });
+  const hookPath = path.join(huskyDir, 'pre-commit');
+  fs.appendFileSync(hookPath, '\nscripts/trackfw-validate.sh\n', { mode: 0o755 });
+  console.log('✓ trackfw entry added to .husky/pre-commit');
+}
+
 function installHusky(rootDir) {
   try {
     execSync('npm install --save-dev husky', { cwd: rootDir, stdio: 'inherit' });
@@ -396,6 +417,13 @@ cmd.action((opts) => {
       } catch (e) {
         console.log(`⚠ agent rules inject partial: ${e.message}`);
       }
+      try {
+        const { injectHooksDetected } = require('../generators/hooks');
+        injectHooksDetected(cwd);
+        console.log('✓ agent hooks injected');
+      } catch (e) {
+        console.warn(`⚠ agent hooks inject partial: ${e.message}`);
+      }
       try {
         const generators = require('../generators/init')
         generators.printArchitectNextSteps(cwd)

package/src/commands/update.js

@@ -72,6 +72,15 @@ cmd.action(() => {
     console.log(`  ⚠ agent rules: ${e.message}`);
   }
 
+  // 1b. Agent hooks (attention signal/cleanup)
+  try {
+    const { injectHooksDetected } = require('../generators/hooks');
+    injectHooksDetected(cwd);
+    console.log('  ✓ agent hooks atualizados');
+  } catch (e) {
+    console.warn(`  ⚠ agent hooks: ${e.message}`);
+  }
+
   // 2. Validate script (trackfw-owned, overwrite)
   try {
     discover.writeValidateScript(cwd);

package/src/generators/hooks.js

@@ -0,0 +1,302 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Lê JSON de arquivo (retorna {} se não existir ou inválido) */
+function readJSON(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8')
+    return JSON.parse(raw)
+  } catch (_) {
+    return {}
+  }
+}
+
+/** Escreve JSON com indent 2 */
+function writeJSON(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8')
+}
+
+/** Verifica se array já tem entry com determinado campo=valor */
+function hasEntry(arr, field, value) {
+  return Array.isArray(arr) && arr.some(e => e && e[field] === value)
+}
+
+// ---------------------------------------------------------------------------
+// Scripts content
+// ---------------------------------------------------------------------------
+
+const SIGNAL_SCRIPT = `#!/usr/bin/env bash
+# trackfw attention signal — PreToolUse/BeforeTool hook
+# Writes .trackfw-attention.json so trackfw serve board shows a banner.
+set -euo pipefail
+
+INPUT=$(cat)
+[ -f "trackfw.yaml" ] || exit 0
+
+if command -v jq &>/dev/null; then
+  TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+  MSG=$(echo "$INPUT" | jq -r '(.tool_input.question // .tool_input.command // ("Agent executing: " + (.tool_name // "unknown"))) | .[0:300]')
+else
+  TOOL=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name',''))" 2>/dev/null || echo "")
+  MSG=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); ti=d.get('tool_input',{}); print((ti.get('question') or ti.get('command') or 'Agent executing: '+d.get('tool_name','unknown'))[:300])" 2>/dev/null || echo "Agent needs attention")
+fi
+
+ROADMAP_DIR=$(grep '^roadmap_dir:' trackfw.yaml 2>/dev/null | awk '{print $2}' | tr -d "\"'" | head -1)
+ROADMAP_DIR=\${ROADMAP_DIR:-docs/roadmaps}
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+mkdir -p "$ROADMAP_DIR"
+printf '{"tool":"%s","message":"%s","level":"action_required","timestamp":"%s"}\\n' \\
+  "$(echo "$TOOL" | sed 's/"/\\\\"/g')" \\
+  "$(echo "$MSG"  | sed 's/"/\\\\"/g; s/$//' | tr -d '\\n')" \\
+  "$TIMESTAMP" > "$ROADMAP_DIR/.trackfw-attention.json"
+
+exit 0
+`
+
+const CLEANUP_SCRIPT = `#!/usr/bin/env bash
+# trackfw attention cleanup — PostToolUse/AfterTool hook
+set -euo pipefail
+
+[ -f "trackfw.yaml" ] || exit 0
+
+ROADMAP_DIR=$(grep '^roadmap_dir:' trackfw.yaml 2>/dev/null | awk '{print $2}' | tr -d "\"'" | head -1)
+ROADMAP_DIR=\${ROADMAP_DIR:-docs/roadmaps}
+
+rm -f "$ROADMAP_DIR/.trackfw-attention.json"
+exit 0
+`
+
+const SIGNAL_CMD = 'scripts/trackfw-attention-signal.sh'
+const CLEANUP_CMD = 'scripts/trackfw-attention-cleanup.sh'
+
+// ---------------------------------------------------------------------------
+// generateAttentionScripts — writes the two shell scripts to scripts/
+// ---------------------------------------------------------------------------
+
+function generateAttentionScripts(cfg, cwd) {
+  const root = cwd || process.cwd()
+  const scriptsDir = path.join(root, 'scripts')
+  fs.mkdirSync(scriptsDir, { recursive: true })
+
+  const signalPath = path.join(scriptsDir, 'trackfw-attention-signal.sh')
+  fs.writeFileSync(signalPath, SIGNAL_SCRIPT, { encoding: 'utf8', mode: 0o755 })
+
+  const cleanupPath = path.join(scriptsDir, 'trackfw-attention-cleanup.sh')
+  fs.writeFileSync(cleanupPath, CLEANUP_SCRIPT, { encoding: 'utf8', mode: 0o755 })
+
+  console.log('  ✓ scripts/trackfw-attention-signal.sh')
+  console.log('  ✓ scripts/trackfw-attention-cleanup.sh')
+}
+
+// ---------------------------------------------------------------------------
+// Claude Code — .claude/settings.json
+// ---------------------------------------------------------------------------
+
+function injectClaudeHooks(cwd) {
+  const filePath = path.join(cwd, '.claude', 'settings.json')
+  const data = readJSON(filePath)
+
+  if (!data.hooks) data.hooks = {}
+
+  // PreToolUse — AskUserQuestion
+  if (!data.hooks.PreToolUse) data.hooks.PreToolUse = []
+  let preEntry = data.hooks.PreToolUse.find(e => e && e.matcher === 'AskUserQuestion')
+  if (!preEntry) {
+    preEntry = { matcher: 'AskUserQuestion', hooks: [] }
+    data.hooks.PreToolUse.push(preEntry)
+  }
+  if (!Array.isArray(preEntry.hooks)) preEntry.hooks = []
+  if (!hasEntry(preEntry.hooks, 'command', SIGNAL_CMD)) {
+    preEntry.hooks.push({ type: 'command', command: SIGNAL_CMD })
+  }
+
+  // PostToolUse — cleanup
+  if (!data.hooks.PostToolUse) data.hooks.PostToolUse = []
+  let postEntry = data.hooks.PostToolUse.find(e => e && e.matcher === 'AskUserQuestion')
+  if (!postEntry) {
+    postEntry = { matcher: 'AskUserQuestion', hooks: [] }
+    data.hooks.PostToolUse.push(postEntry)
+  }
+  if (!Array.isArray(postEntry.hooks)) postEntry.hooks = []
+  if (!hasEntry(postEntry.hooks, 'command', CLEANUP_CMD)) {
+    postEntry.hooks.push({ type: 'command', command: CLEANUP_CMD })
+  }
+
+  writeJSON(filePath, data)
+}
+
+// ---------------------------------------------------------------------------
+// Codex — .codex/hooks.json
+// ---------------------------------------------------------------------------
+
+function injectCodexHooks(cwd) {
+  const filePath = path.join(cwd, '.codex', 'hooks.json')
+  const data = readJSON(filePath)
+
+  if (!data.PreToolUse) data.PreToolUse = []
+  if (!data.PostToolUse) data.PostToolUse = []
+
+  if (!hasEntry(data.PreToolUse, 'command', SIGNAL_CMD)) {
+    data.PreToolUse.push({ matcher: '.*', command: SIGNAL_CMD })
+  }
+  if (!hasEntry(data.PostToolUse, 'command', CLEANUP_CMD)) {
+    data.PostToolUse.push({ matcher: '.*', command: CLEANUP_CMD })
+  }
+
+  writeJSON(filePath, data)
+}
+
+// ---------------------------------------------------------------------------
+// Gemini — .gemini/settings.json
+// ---------------------------------------------------------------------------
+
+function injectGeminiHooks(cwd) {
+  const filePath = path.join(cwd, '.gemini', 'settings.json')
+  const data = readJSON(filePath)
+
+  if (!data.hooks) data.hooks = {}
+
+  if (!Array.isArray(data.hooks.BeforeTool)) data.hooks.BeforeTool = []
+  if (!hasEntry(data.hooks.BeforeTool, 'command', SIGNAL_CMD)) {
+    data.hooks.BeforeTool.push({ command: SIGNAL_CMD })
+  }
+
+  if (!Array.isArray(data.hooks.AfterTool)) data.hooks.AfterTool = []
+  if (!hasEntry(data.hooks.AfterTool, 'command', CLEANUP_CMD)) {
+    data.hooks.AfterTool.push({ command: CLEANUP_CMD })
+  }
+
+  writeJSON(filePath, data)
+}
+
+// ---------------------------------------------------------------------------
+// Kiro — .kiro/hooks/trackfw-attention.json (dedicated file, safe overwrite)
+// ---------------------------------------------------------------------------
+
+function injectKiroHooks(cwd) {
+  const filePath = path.join(cwd, '.kiro', 'hooks', 'trackfw-attention.json')
+  const data = {
+    hooks: [
+      {
+        name: 'trackfw-attention-signal',
+        event: 'PreToolUse',
+        matcher: { tool_name: '.*' },
+        action: { type: 'command', command: SIGNAL_CMD },
+      },
+      {
+        name: 'trackfw-attention-cleanup',
+        event: 'PostToolUse',
+        matcher: { tool_name: '.*' },
+        action: { type: 'command', command: CLEANUP_CMD },
+      },
+    ],
+  }
+  writeJSON(filePath, data)
+}
+
+// ---------------------------------------------------------------------------
+// Copilot — .github/hooks/trackfw-attention.json (dedicated file, safe overwrite)
+// ---------------------------------------------------------------------------
+
+function injectCopilotHooks(cwd) {
+  const filePath = path.join(cwd, '.github', 'hooks', 'trackfw-attention.json')
+  const data = {
+    hooks: [
+      { event: 'preToolUse', run: SIGNAL_CMD },
+      { event: 'postToolUse', run: CLEANUP_CMD },
+    ],
+  }
+  writeJSON(filePath, data)
+}
+
+// ---------------------------------------------------------------------------
+// Cursor — .cursor/hooks.json
+// ---------------------------------------------------------------------------
+
+function injectCursorHooks(cwd) {
+  const filePath = path.join(cwd, '.cursor', 'hooks.json')
+  const data = readJSON(filePath)
+
+  if (!Array.isArray(data.preToolUse)) data.preToolUse = []
+  if (!hasEntry(data.preToolUse, 'command', SIGNAL_CMD)) {
+    data.preToolUse.push({ command: SIGNAL_CMD })
+  }
+
+  if (!Array.isArray(data.postToolUse)) data.postToolUse = []
+  if (!hasEntry(data.postToolUse, 'command', CLEANUP_CMD)) {
+    data.postToolUse.push({ command: CLEANUP_CMD })
+  }
+
+  writeJSON(filePath, data)
+}
+
+// ---------------------------------------------------------------------------
+// injectHooksDetected — public entry point
+// ---------------------------------------------------------------------------
+
+function injectHooksDetected(cwd) {
+  const root = cwd || process.cwd()
+
+  const detections = {
+    claude: {
+      check: () =>
+        fs.existsSync(path.join(root, '.claude')) ||
+        fs.existsSync(path.join(root, 'CLAUDE.md')),
+      fn: injectClaudeHooks,
+    },
+    codex: {
+      check: () =>
+        fs.existsSync(path.join(root, 'AGENTS.md')) ||
+        fs.existsSync(path.join(root, '.codex')),
+      fn: injectCodexHooks,
+    },
+    gemini: {
+      check: () =>
+        fs.existsSync(path.join(root, 'GEMINI.md')) ||
+        fs.existsSync(path.join(root, '.gemini')),
+      fn: injectGeminiHooks,
+    },
+    kiro: {
+      check: () => fs.existsSync(path.join(root, '.kiro')),
+      fn: injectKiroHooks,
+    },
+    copilot: {
+      check: () =>
+        fs.existsSync(path.join(root, '.github', 'copilot-instructions.md')),
+      fn: injectCopilotHooks,
+    },
+    cursor: {
+      check: () => fs.existsSync(path.join(root, '.cursor')),
+      fn: injectCursorHooks,
+    },
+  }
+
+  for (const [name, { check, fn }] of Object.entries(detections)) {
+    if (!check()) continue
+    try {
+      fn(root)
+    } catch (e) {
+      console.warn(`  ⚠ hooks (${name}): ${e.message}`)
+    }
+  }
+}
+
+module.exports = {
+  generateAttentionScripts,
+  injectClaudeHooks,
+  injectCodexHooks,
+  injectGeminiHooks,
+  injectKiroHooks,
+  injectCopilotHooks,
+  injectCursorHooks,
+  injectHooksDetected,
+}

package/src/generators/init.js

@@ -27,6 +27,7 @@ async function scaffold(cfg) {
 
   writeTrackfwConfig(cfg)
   generateValidateScript(cfg)
+  generateAttentionScripts(cfg)
   generateCIWorkflow(cfg)
   generateGitHooks(cfg)
   generateCommitMsgHook(cfg)
@@ -116,6 +117,15 @@ trackfw validate
   return base
 }
 
+// ---------------------------------------------------------------------------
+// scripts/trackfw-attention-signal.sh + trackfw-attention-cleanup.sh
+// ---------------------------------------------------------------------------
+
+function generateAttentionScripts(cfg, cwd) {
+  const { generateAttentionScripts: gen } = require('./hooks')
+  gen(cfg, cwd || process.cwd())
+}
+
 // ---------------------------------------------------------------------------
 // CI workflows
 // ---------------------------------------------------------------------------
@@ -336,30 +346,14 @@ function trackfwRulesBlock() {
 This project uses **trackfw** for AI-native delivery governance.
 Chain: \`ADR → REQ → ROADMAP\` · States: \`backlog / analyzing / wip / blocked / done / abandoned\`
 
-\`\`\`
-backlog     → roadmaps aguardando execução
-analyzing   → roadmap em análise/validação pré-wip
-wip         → roadmap em execução ativa (máximo 1)
-blocked     → impedido por dependência ou decisão
-done        → concluído e validado
-abandoned   → descontinuado ou superado
-\`\`\`
-
 ### 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. **Ciclo de vida do ML — obrigatório:**
-   - Ao **iniciar** um ML: edite o roadmap alterando \`**Status:** ⬜ Pendente\` → \`**Status:** 🔄 Em andamento\` e faça commit do roadmap.
-   - Ao **concluir** um ML: edite o roadmap alterando \`**Status:** 🔄 Em andamento\` → \`**Status:** ✅ Concluído\` e inclua essa mudança no commit do ML.
-   - Ao **analisar** um roadmap antes de iniciar: mova o arquivo de \`backlog/\` para \`analyzing/\`; só mova para \`wip/\` ao começar a codificar de fato.
-
-### 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 (\`backlog\`, \`analyzing\`, \`wip\`, \`blocked\`, \`done\`, \`abandoned\`)
-- \`trackfw serve\` — live Kanban board at http://localhost:4080
+4. **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.
 
 ### Attention Signal (when you need user input during a task)
 Write \`docs/roadmaps/.trackfw-attention.json\`:
@@ -369,14 +363,10 @@ Write \`docs/roadmaps/.trackfw-attention.json\`:
 Delete the file when resolved. Visible as a live banner in \`trackfw serve\`.
 ` +
 '\n### Architecture Directives (mandatory)\n' +
-'- **3-layer separation:** frontend / backend / database — never mix concerns\n' +
-'- **No in-memory data:** always database + ORM (never arrays/globals for persistence)\n' +
-'- **Auth from day 1:** never defer — refactoring auth later is very costly\n' +
-'- **Docker + .env from day 1:** containerize early; all config via env vars\n' +
-'- **2-layer validation:** frontend (UX) + backend (security) — never only one\n' +
-'- **API-first:** define OpenAPI contract before coding frontend/backend integration\n' +
-'- **Security wave:** include a red-team review wave in every feature roadmap\n' +
-'- **Test coverage:** TDD for critical logic; min 60% (prototype) / 80% (production)\n' +
+'- **3-layer arch + no in-memory data:** frontend / backend / database; always DB + ORM — never arrays/globals\n' +
+'- **Auth + Docker + .env from day 1:** never defer auth; containerize early; all config via env vars\n' +
+'- **2-layer validation + API-first:** frontend (UX) + backend (security); define OpenAPI contract first\n' +
+'- **Security wave + test coverage:** red-team review in every roadmap; TDD for critical; min 60%/80%\n' +
 '- Use `/trackfw:architect` to define stack before the first REQ\n' +
 RULES_END
 }
@@ -893,14 +883,7 @@ Explique a arquitetura com uma metáfora de negócio:
 - **Backend** = a cozinha: onde as regras de negócio acontecem, nunca exposta diretamente
 - **Banco de dados** = a despensa: onde os dados ficam guardados, acessada só pela cozinha"
 
-Reforce as regras obrigatórias:
-- **Nunca dados em memória** (arrays, variáveis globais): sempre banco + ORM
-- **Docker + .env desde o dia 1**: facilita deploys e evita problemas de ambiente
-- **Auth desde o início**: nunca deixe para depois — refatorar auth é muito custoso
-- **Validação em 2 camadas**: frontend (UX) + backend (segurança)
-- **API-first**: defina o contrato OpenAPI antes de codar frontend e backend juntos
-- **Red team wave**: reserve 1 wave de segurança no roadmap para revisar vulnerabilidades
-- **Cobertura mínima de testes**: 60% (protótipo) / 80% (produção)
+Reforce 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).
 
 ---
 
@@ -1016,7 +999,7 @@ function generateClaudeCommandsForce(rootDir) {
     '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 regras obrigatórias:\n- **Nunca dados em memória** (arrays, variáveis globais): sempre banco + ORM\n- **Docker + .env desde o dia 1**: facilita deploys e evita problemas de ambiente\n- **Auth desde o início**: nunca deixe para depois — refatorar auth é muito custoso\n- **Validação em 2 camadas**: frontend (UX) + backend (segurança)\n- **API-first**: defina o contrato OpenAPI antes de codar frontend e backend juntos\n- **Red team wave**: reserve 1 wave de segurança no roadmap para revisar vulnerabilidades\n- **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\`\`\``,
+    '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)) {
@@ -1096,6 +1079,7 @@ module.exports = {
   scaffold,
   writeTrackfwConfig,
   generateValidateScript,
+  generateAttentionScripts,
   generateCIWorkflow,
   generateGitHooks,
   generateCommitMsgHook,

package/src/validator/index.js

@@ -735,6 +735,33 @@ function validateFilenameUniqueness() {
   return violations
 }
 
+// validateBranchHasWIPRoadmap — verifica que branch feat/fix/refactor tem ao menos um roadmap em wip/
+function validateBranchHasWIPRoadmap() {
+  const { execSync } = require('child_process')
+  let branch
+  try {
+    branch = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
+  } catch {
+    return [] // não é git repo ou HEAD detached
+  }
+  if (!branch.startsWith('feat/') && !branch.startsWith('fix/') && !branch.startsWith('refactor/')) {
+    return []
+  }
+
+  const cfg = config.load()
+  const wipDirs = resolveWIPDirs(cfg)
+  let total = 0
+  for (const wipDir of wipDirs) {
+    const files = listDir(wipDir).filter(f => f.endsWith('.md'))
+    total += files.length
+  }
+
+  if (total === 0) {
+    return [`branch "${branch}" is a feat/fix/refactor branch but no roadmap is in wip/ — create governance artifacts first:\n  trackfw req new "title"\n  trackfw roadmap new "title"\n  trackfw roadmap move <name> wip`]
+  }
+  return []
+}
+
 // _itemMeta: mapa de message → { rule, file } para enriquecer saída JSON.
 // Populado em applyRule e nos pushs diretos do validateUnfiltered.
 // Permanece em memória apenas durante a execução de uma chamada validate*.
@@ -816,6 +843,7 @@ async function validateUnfiltered() {
   applyRule('ref_targets_exist',    validateRefTargetsExist(),             violations, warnings)
   applyRule('folder_status',        validateFolderStatusCoherence(),       violations, warnings)
   applyRule('filename_uniqueness',  validateFilenameUniqueness(),          violations, warnings)
+  applyRule('branch_has_wip_roadmap', validateBranchHasWIPRoadmap(),      violations, warnings)
   applyRule('blocked_by_draft_adr', validateREQsNotBlockedByDraftADRs(),  violations, warnings)
 
   // Regras configuráveis via applyRule (popula _itemMeta automaticamente)
@@ -979,6 +1007,7 @@ module.exports = {
   validateRefTargetsExist,
   validateFolderStatusCoherence,
   validateFilenameUniqueness,
+  validateBranchHasWIPRoadmap,
   // novas funções ML-2B
   contentHasMarker,
   ruleSeverity,