trackfw 2.11.0 → 2.12.1

package/README.md

@@ -374,6 +374,20 @@ The governance structure (`docs/adr/`, `docs/req/`, `docs/roadmaps/`) is always
 
 ---
 
+## Compared to alternatives
+
+| Tool | What it does | What's missing |
+|---|---|---|
+| **adr-tools** | Creates ADR files | No link to requirements or roadmaps |
+| **madr** | ADR template format | No enforcement, no delivery tracking |
+| **Linear / Jira** | Task tracking | No traceability to architectural decisions |
+| **Kosli** | SDLC compliance for regulated industries | SaaS, accounts, cost — not for every team |
+| **trackfw** | Enforces the full chain: decision → requirement → roadmap → delivery | — |
+
+trackfw is the only open-source CLI that links ADRs to requirements, requirements to roadmaps, and enforces the chain as a pre-commit and CI gate — with native support for AI coding assistants.
+
+---
+
 ## Contributing
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "trackfw",
-  "version": "2.11.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).",
+  "version": "2.12.1",
+  "description": "Governance CLI for AI-native software delivery. Enforces traceability: ADR → REQ → ROADMAP → kanban. Pre-commit gate + CI integration. Native support for Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, Amazon Q.",
   "keywords": [
     "cli",
     "adr",
@@ -13,6 +13,16 @@
     "ai-agents",
     "developer-tools",
     "kanban",
+    "traceability",
+    "software-governance",
+    "ai-governance",
+    "pre-commit",
+    "developer-experience",
+    "technical-debt",
+    "claude-code",
+    "gemini",
+    "cursor",
+    "copilot",
     "req",
     "trackfw"
   ],

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
 // ---------------------------------------------------------------------------
@@ -1069,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,