trackfw 2.14.0 → 2.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "2.14.0",
+  "version": "2.15.1",
   "description": "Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, and Amazon Q.",
   "keywords": [
     "cli",

package/src/commands/update.js

@@ -89,8 +89,9 @@ cmd.action(() => {
 
   // 1b. Agent hooks (attention signal/cleanup)
   try {
-    const { injectHooksDetected } = require('../generators/hooks');
+    const { injectHooksDetected, generateAttentionScripts } = require('../generators/hooks');
     injectHooksDetected(cwd);
+    generateAttentionScripts(cfg, cwd);
     console.log('  ✓ agent hooks atualizados');
   } catch (e) {
     console.warn(`  ⚠ agent hooks: ${e.message}`);

package/src/config/index.js

@@ -1,13 +1,25 @@
 'use strict';
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 
+function expandPath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return filePath;
+  if (filePath === '~') {
+    return os.homedir();
+  }
+  if (filePath.startsWith('~/') || filePath.startsWith('~\\')) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}
+
 function defaults() {
   return {
-    adrDirs: ['docs/adr'],
-    reqDir: 'docs/req',
-    roadmapDir: 'docs/roadmaps',
+    adrDirs: ['docs/adr'].map(expandPath),
+    reqDir: expandPath('docs/req'),
+    roadmapDir: expandPath('docs/roadmaps'),
     roadmapNamespacing: 'flat',
     agents: [],
     governanceMode: '',
@@ -15,6 +27,7 @@ function defaults() {
     wipLimit: 1,
     wipBySquad: false,
     requireReqInCommit: false,
+    strictCiPaths: false,
     traceIdField: '',
     // NOVOS campos:
     linkFields: {
@@ -78,7 +91,7 @@ function parse(content, cfg) {
   let rules = {};
 
   function flushBlocks() {
-    if (inAdrDirs && adrDirs.length) cfg.adrDirs = adrDirs;
+    if (inAdrDirs && adrDirs.length) cfg.adrDirs = adrDirs.map(expandPath);
     if (inAgents && agents.length) cfg.agents = agents;
     if (inLinkFields) {
       if (inLinkFieldsReq && linkFieldsReq.length) cfg.linkFields.req = linkFieldsReq;
@@ -108,7 +121,11 @@ function parse(content, cfg) {
 
     if (hasIndent) {
       if (inAdrDirs) {
-        if (line.startsWith('- ')) adrDirs.push(line.slice(2).trim());
+        if (line.startsWith('- ')) {
+          let val = line.slice(2).trim();
+          val = val.replace(/^["']|["']$/g, '');
+          adrDirs.push(expandPath(val));
+        }
         continue;
       }
       if (inAgents) {
@@ -166,8 +183,8 @@ function parse(content, cfg) {
 
     switch (key) {
       case 'adr_dirs':              inAdrDirs = true; adrDirs = []; break;
-      case 'req_dir':               cfg.reqDir = val.replace(/^["']|["']$/g, ''); break;
-      case 'roadmap_dir':           cfg.roadmapDir = val.replace(/^["']|["']$/g, ''); break;
+      case 'req_dir':               cfg.reqDir = expandPath(val.replace(/^["']|["']$/g, '')); break;
+      case 'roadmap_dir':           cfg.roadmapDir = expandPath(val.replace(/^["']|["']$/g, '')); break;
       case 'roadmap_namespacing':   cfg.roadmapNamespacing = val; break;
       case 'agents':                inAgents = true; agents = []; break;
       case 'governance_mode':       cfg.governanceMode = val; break;
@@ -175,6 +192,7 @@ function parse(content, cfg) {
       case 'wip_limit':             { const n = parseInt(val, 10); if (n > 0) cfg.wipLimit = n; break; }
       case 'wip_by_squad':          cfg.wipBySquad = val === 'true'; break;
       case 'require_req_in_commit': cfg.requireReqInCommit = val === 'true'; break;
+      case 'strict_ci_paths':       cfg.strictCiPaths = val === 'true'; break;
       case 'trace_id_field':        cfg.traceIdField = val.replace(/^["']|["']$/g, ''); break;
       case 'link_fields':           inLinkFields = true; break;
       case 'acceptance_markers':    inAcceptanceMarkers = true; acceptanceMarkers = []; break;
@@ -189,4 +207,5 @@ function parse(content, cfg) {
 const NAMESPACING_FLAT = 'flat';
 const NAMESPACING_BY_AGENT = 'by_agent';
 
-module.exports = { load, reset, defaults, NAMESPACING_FLAT, NAMESPACING_BY_AGENT };
+module.exports = { load, reset, defaults, expandPath, NAMESPACING_FLAT, NAMESPACING_BY_AGENT };
+

package/src/generators/hooks.js

@@ -28,37 +28,67 @@ function hasEntry(arr, field, value) {
   return Array.isArray(arr) && arr.some(e => e && e[field] === value)
 }
 
+/** Merge helper para arrays de hooks tipo Claude / Codex / Gemini */
+function mergeClaudeHookArray(existing, matcher, command) {
+  const arr = Array.isArray(existing) ? existing : []
+
+  for (const item of arr) {
+    if (!item || item.matcher !== matcher) continue
+    const innerHooks = Array.isArray(item.hooks) ? item.hooks : []
+    if (innerHooks.some(h => h && h.command === command)) {
+      return arr
+    }
+  }
+
+  let entry = arr.find(e => e && e.matcher === matcher)
+  if (!entry) {
+    entry = { matcher, hooks: [] }
+    arr.push(entry)
+  }
+  if (!Array.isArray(entry.hooks)) entry.hooks = []
+  if (!entry.hooks.some(h => h && h.command === command)) {
+    entry.hooks.push({ type: 'command', command })
+  }
+
+  return arr
+}
+
 // ---------------------------------------------------------------------------
 // Scripts content
 // ---------------------------------------------------------------------------
 
 const SIGNAL_SCRIPT = `#!/usr/bin/env bash
-# trackfw attention signal — permission/notification hook
-# Writes .trackfw-attention.json so trackfw serve board shows a banner.
+# trackfw attention signal — PreToolUse/BeforeTool hook
 set -euo pipefail
 
 INPUT=$(cat)
-HOOK_CWD=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('cwd',''))" 2>/dev/null || true)
-[ -n "$HOOK_CWD" ] && cd "$HOOK_CWD"
+
+# Script is intentionally a no-op when executed outside the project root
 [ -f "trackfw.yaml" ] || exit 0
 
 if command -v jq &>/dev/null; then
-  TOOL=$(echo "$INPUT" | jq -r '.tool_name // .notification_type // ""')
-  MSG=$(echo "$INPUT" | jq -r '(.message // .tool_input.description // .tool_input.question // .tool_input.command // ("Approval required for: " + (.tool_name // .notification_type // "unknown"))) | .[0:300]')
+  TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+  MSG=$(echo "$INPUT" | jq -r '(.tool_input.question // .tool_input.command // "Agent is 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') or d.get('notification_type') or '')" 2>/dev/null || echo "")
-  MSG=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); ti=d.get('tool_input',{}); print((d.get('message') or ti.get('description') or ti.get('question') or ti.get('command') or 'Approval required for: '+(d.get('tool_name') or d.get('notification_type') or 'unknown'))[:300])" 2>/dev/null || echo "Agent needs attention")
+  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 is 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=$(grep '^roadmap_dir:' trackfw.yaml 2>/dev/null | head -1 | sed 's/^roadmap_dir:[[:space:]]*//; s/[[:space:]]*#.*$//' | tr -d '"' | tr -d "'" || true)
 ROADMAP_DIR=\${ROADMAP_DIR:-docs/roadmaps}
 
+case "$ROADMAP_DIR" in
+  /*|../*|*/../*|*/..|..) ROADMAP_DIR="docs/roadmaps" ;;
+esac
+
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+TOOL_ESC=$(echo "$TOOL" | tr -d '\\000-\\037' | sed -e 's/\\\\/\\\\\\\\/g' -e 's/"/\\\\"/g')
+MSG_ESC=$(echo "$MSG" | tr -d '\\000-\\037' | sed -e 's/\\\\/\\\\\\\\/g' -e 's/"/\\\\"/g')
 
 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')" \\
+  "$TOOL_ESC" \\
+  "$MSG_ESC" \\
   "$TIMESTAMP" > "$ROADMAP_DIR/.trackfw-attention.json"
 
 exit 0
@@ -68,14 +98,16 @@ const CLEANUP_SCRIPT = `#!/usr/bin/env bash
 # trackfw attention cleanup — PostToolUse/AfterTool hook
 set -euo pipefail
 
-INPUT=$(cat)
-HOOK_CWD=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('cwd',''))" 2>/dev/null || true)
-[ -n "$HOOK_CWD" ] && cd "$HOOK_CWD"
+# Script is intentionally a no-op when executed outside the project root
 [ -f "trackfw.yaml" ] || exit 0
 
-ROADMAP_DIR=$(grep '^roadmap_dir:' trackfw.yaml 2>/dev/null | awk '{print $2}' | tr -d "\"'" | head -1)
+ROADMAP_DIR=$(grep '^roadmap_dir:' trackfw.yaml 2>/dev/null | head -1 | sed 's/^roadmap_dir:[[:space:]]*//; s/[[:space:]]*#.*$//' | tr -d '"' | tr -d "'" || true)
 ROADMAP_DIR=\${ROADMAP_DIR:-docs/roadmaps}
 
+case "$ROADMAP_DIR" in
+  /*|../*|*/../*|*/..|..) ROADMAP_DIR="docs/roadmaps" ;;
+esac
+
 rm -f "$ROADMAP_DIR/.trackfw-attention.json"
 exit 0
 `
@@ -111,30 +143,8 @@ function injectClaudeHooks(cwd) {
   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 })
-  }
+  data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'AskUserQuestion', SIGNAL_CMD)
+  data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'AskUserQuestion', CLEANUP_CMD)
 
   writeJSON(filePath, data)
 }
@@ -148,24 +158,8 @@ function injectCodexHooks(cwd) {
   const data = readJSON(filePath)
 
   if (!data.hooks) data.hooks = {}
-  if (!Array.isArray(data.hooks.PermissionRequest)) data.hooks.PermissionRequest = []
-  if (!Array.isArray(data.hooks.PostToolUse)) data.hooks.PostToolUse = []
-
-  const hasNestedCommand = (entries, command) => entries.some(
-    entry => Array.isArray(entry && entry.hooks) && entry.hooks.some(h => h && h.command === command)
-  )
-  if (!hasNestedCommand(data.hooks.PermissionRequest, SIGNAL_CMD)) {
-    data.hooks.PermissionRequest.push({
-      matcher: '.*',
-      hooks: [{ type: 'command', command: SIGNAL_CMD, timeout: 10, statusMessage: 'Waiting for approval' }],
-    })
-  }
-  if (!hasNestedCommand(data.hooks.PostToolUse, CLEANUP_CMD)) {
-    data.hooks.PostToolUse.push({
-      matcher: '.*',
-      hooks: [{ type: 'command', command: CLEANUP_CMD, timeout: 10 }],
-    })
-  }
+  data.hooks.PermissionRequest = mergeClaudeHookArray(data.hooks.PermissionRequest, '.*', SIGNAL_CMD)
+  data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, '.*', CLEANUP_CMD)
 
   writeJSON(filePath, data)
 }
@@ -179,27 +173,8 @@ function injectGeminiHooks(cwd) {
   const data = readJSON(filePath)
 
   if (!data.hooks) data.hooks = {}
-
-  if (!Array.isArray(data.hooks.Notification)) data.hooks.Notification = []
-  if (!data.hooks.Notification.some(entry =>
-    entry && entry.matcher === 'ToolPermission' &&
-    Array.isArray(entry.hooks) && entry.hooks.some(hook => hook && hook.command === SIGNAL_CMD)
-  )) {
-    data.hooks.Notification.push({
-      matcher: 'ToolPermission',
-      hooks: [{ name: 'trackfw-attention-signal', type: 'command', command: SIGNAL_CMD, timeout: 10000 }],
-    })
-  }
-
-  if (!Array.isArray(data.hooks.AfterTool)) data.hooks.AfterTool = []
-  if (!data.hooks.AfterTool.some(entry =>
-    Array.isArray(entry && entry.hooks) && entry.hooks.some(hook => hook && hook.command === CLEANUP_CMD)
-  )) {
-    data.hooks.AfterTool.push({
-      matcher: '*',
-      hooks: [{ name: 'trackfw-attention-cleanup', type: 'command', command: CLEANUP_CMD, timeout: 10000 }],
-    })
-  }
+  data.hooks.Notification = mergeClaudeHookArray(data.hooks.Notification, 'ToolPermission', SIGNAL_CMD)
+  data.hooks.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, '*', CLEANUP_CMD)
 
   writeJSON(filePath, data)
 }
@@ -214,12 +189,14 @@ function injectKiroHooks(cwd) {
     hooks: [
       {
         name: 'trackfw-attention-signal',
+        description: 'Signals trackfw board when agent executes a tool',
         event: 'PreToolUse',
         matcher: { tool_name: '.*' },
         action: { type: 'command', command: SIGNAL_CMD },
       },
       {
         name: 'trackfw-attention-cleanup',
+        description: 'Clears trackfw board attention after tool completes',
         event: 'PostToolUse',
         matcher: { tool_name: '.*' },
         action: { type: 'command', command: CLEANUP_CMD },
@@ -236,11 +213,16 @@ function injectKiroHooks(cwd) {
 function injectCopilotHooks(cwd) {
   const filePath = path.join(cwd, '.github', 'hooks', 'trackfw-attention.json')
   const data = {
-    version: 1,
-    hooks: {
-      preToolUse: [{ type: 'command', bash: SIGNAL_CMD, cwd: '.', timeoutSec: 10 }],
-      postToolUse: [{ type: 'command', bash: CLEANUP_CMD, cwd: '.', timeoutSec: 10 }],
-    },
+    hooks: [
+      {
+        event: 'preToolUse',
+        run: SIGNAL_CMD,
+      },
+      {
+        event: 'postToolUse',
+        run: CLEANUP_CMD,
+      },
+    ],
   }
   writeJSON(filePath, data)
 }
@@ -266,6 +248,15 @@ function injectCursorHooks(cwd) {
   writeJSON(filePath, data)
 }
 
+// ---------------------------------------------------------------------------
+// Windsurf — update .windsurfrules with attention instruction
+// ---------------------------------------------------------------------------
+
+function injectWindsurfHooks(cwd) {
+  const { injectRulesForTool } = require('./init')
+  return injectRulesForTool('windsurf', cwd)
+}
+
 // ---------------------------------------------------------------------------
 // injectHooksDetected — public entry point
 // ---------------------------------------------------------------------------
@@ -298,13 +289,18 @@ function injectHooksDetected(cwd) {
     },
     copilot: {
       check: () =>
-        fs.existsSync(path.join(root, '.github', 'copilot-instructions.md')),
+        fs.existsSync(path.join(root, '.github', 'copilot-instructions.md')) ||
+        fs.existsSync(path.join(root, '.github', 'hooks')),
       fn: injectCopilotHooks,
     },
     cursor: {
       check: () => fs.existsSync(path.join(root, '.cursor')),
       fn: injectCursorHooks,
     },
+    windsurf: {
+      check: () => fs.existsSync(path.join(root, '.windsurfrules')),
+      fn: injectWindsurfHooks,
+    },
   }
 
   for (const [name, { check, fn }] of Object.entries(detections)) {
@@ -325,5 +321,6 @@ module.exports = {
   injectKiroHooks,
   injectCopilotHooks,
   injectCursorHooks,
+  injectWindsurfHooks,
   injectHooksDetected,
 }

package/src/generators/init.js

@@ -15,25 +15,29 @@ const GOV_DIRS = [
   'docs/roadmaps/abandoned',
 ]
 
+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.'
+
 /**
  * scaffold(cfg) — cria diretórios de governança e gera arquivos de configuração.
  * cfg = { projectName, projectType, frontend, backend, pkgManager, hooks, ci }
  */
-async function scaffold(cfg) {
+async function scaffold(cfg, cwd) {
+  const root = cwd || process.cwd()
   for (const dir of GOV_DIRS) {
-    fs.mkdirSync(dir, { recursive: true })
+    fs.mkdirSync(path.join(root, dir), { recursive: true })
     console.log(`  ✓ ${dir}`)
   }
 
-  writeTrackfwConfig(cfg)
-  generateValidateScript(cfg)
-  generateAttentionScripts(cfg)
-  generateCIWorkflow(cfg)
-  generateGitHooks(cfg)
-  generateCommitMsgHook(cfg)
-  generateClaudeMD(cfg)
-  if (cfg.backend === 'java') generatePomXml(cfg)
-  generateClaudeCommands()
+  writeTrackfwConfig(cfg, root)
+  generateValidateScript(cfg, root)
+  generateAttentionScripts(cfg, root)
+  generateCIWorkflow(cfg, root)
+  generateGitHooks(cfg, root)
+  generateCommitMsgHook(cfg, root)
+  generateClaudeMD(cfg, root)
+  if (cfg.backend === 'java') generatePomXml(cfg, root)
+  generateClaudeCommands(root)
+  injectHooksDetected(root)
 }
 
 // ---------------------------------------------------------------------------
@@ -126,6 +130,11 @@ function generateAttentionScripts(cfg, cwd) {
   gen(cfg, cwd || process.cwd())
 }
 
+function injectHooksDetected(cwd) {
+  const { injectHooksDetected: inject } = require('./hooks')
+  inject(cwd || process.cwd())
+}
+
 // ---------------------------------------------------------------------------
 // CI workflows
 // ---------------------------------------------------------------------------
@@ -354,6 +363,7 @@ Chain: \`ADR → REQ → ROADMAP\` · States: \`backlog / analyzing / wip / bloc
    - 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}**
 
 ### Attention Signal (when you need user input during a task)
 Write \`docs/roadmaps/.trackfw-attention.json\`:
@@ -361,14 +371,22 @@ Write \`docs/roadmaps/.trackfw-attention.json\`:
 {"roadmap":"file.md","ml":"ML-1A","message":"what you need","level":"action_required","timestamp":"ISO8601Z"}
 \`\`\`
 Delete the file when resolved. Visible as a live banner in \`trackfw serve\`.
-` +
-'\n### Architecture Directives (mandatory)\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
+
+> **Windsurf users:** before asking the user a question or requesting approval, write
+> \`<roadmap_dir>/.trackfw-attention.json\` manually — there is no automatic hook for this.
+> Delete the file after the user responds.
+
+### Architecture Directives (mandatory)
+- **3-layer separation:** frontend / backend / database — never mix concerns
+- **No in-memory data:** always database + ORM (never arrays/globals for persistence)
+- **Auth from day 1:** never defer — refactoring auth later is very costly
+- **Docker + .env from day 1:** containerize early; all config via env vars
+- **2-layer validation:** frontend (UX) + backend (security) — never only one
+- **API-first:** define OpenAPI contract before coding frontend/backend integration
+- **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
+` + RULES_END
 }
 
 /**
@@ -473,11 +491,13 @@ function generateClaudeMD(cfg) {
   content += '   - Ao **concluir** um ML: edite o roadmap alterando `**Status:** 🔄 Em andamento` → `**Status:** ✅ Concluído` e inclua essa mudança no commit do ML.\n'
   content += '   - 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.\n'
   content += '5. **Run `trackfw validate` before every commit.** Zero violations required.\n'
-  content += '6. **ADRs before decisions.** Any architectural or technical decision must have an ADR (`/trackfw:adr`).\n\n'
+  content += '6. **ADRs before decisions.** Any architectural or technical decision must have an ADR (`/trackfw:adr`).\n'
+  content += `7. **${GLOBAL_ADRS_DIRECTIVE}**\n\n`
 
   content += '## Slash commands (Claude Code)\n\n'
   content += '| Command | When to use |\n'
   content += '|---|---|\n'
+  content += '| `/trackfw:architect` | Guide stack and architecture decisions |\n'
   content += '| `/trackfw:implement <req>` | **Start here** — orchestrates full implementation flow |\n'
   content += '| `/trackfw:adr <title>` | Before any architectural decision |\n'
   content += '| `/trackfw:req <title>` | Before any implementation work |\n'
@@ -1085,6 +1105,7 @@ function printArchitectNextSteps(cwd) {
 
 module.exports = {
   GOV_DIRS,
+  GLOBAL_ADRS_DIRECTIVE,
   scaffold,
   writeTrackfwConfig,
   generateValidateScript,
@@ -1105,6 +1126,7 @@ module.exports = {
   installIntegrationTarget,
   injectRulesForTool,
   injectRulesDetected,
+  injectHooksDetected,
   trackfwRulesBlock,
   printArchitectNextSteps,
 }

package/src/integrations/manager.js

@@ -28,7 +28,7 @@ class IntegrationManager {
     } else if (path.isAbsolute(destination)) {
       resolved = path.normalize(destination)
     } else {
-      if (!destination || path.normalize(destination) !== destination || destination === '.' || destination.startsWith(`..${path.sep}`)) throw new Error(`Unsafe destination: ${destination}`)
+      if (!destination || path.posix.normalize(destination) !== destination || destination === '.' || destination.startsWith('../')) throw new Error(`Unsafe destination: ${destination}`)
       resolved = path.resolve(root, destination)
     }
     const rel = path.relative(root, resolved)

package/src/validator/index.js

@@ -11,10 +11,11 @@ const STALE_WIP_DAYS = 7
 // listDir retorna array de nomes de arquivo (não-diretórios) em dir.
 // Retorna [] se o diretório não existir.
 function listDir(dir) {
+  const expanded = config.expandPath ? config.expandPath(dir) : dir
   try {
-    return fs.readdirSync(dir).filter(name => {
+    return fs.readdirSync(expanded).filter(name => {
       try {
-        return !fs.statSync(path.join(dir, name)).isDirectory()
+        return !fs.statSync(path.join(expanded, name)).isDirectory()
       } catch (_) {
         return false
       }
@@ -24,9 +25,17 @@ function listDir(dir) {
   }
 }
 
-// walkDirMd retorna basenames de todos .md recursivamente dentro de dir.
-function walkDirMd(dir) {
+// isInsideDir retorna true se childPath estiver contido ou for igual a parentDir.
+function isInsideDir(parentDir, childPath) {
+  if (!parentDir || !childPath) return false
+  const rel = path.relative(path.resolve(parentDir), path.resolve(childPath))
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+}
+
+// walkDirMdWithPaths retorna { name, fullPath } de todos .md recursivamente dentro de dir.
+function walkDirMdWithPaths(dir) {
   const results = []
+  const expandedDir = config.expandPath ? config.expandPath(dir) : dir
   function walk(d) {
     let entries
     try { entries = fs.readdirSync(d) } catch (_) { return }
@@ -34,19 +43,25 @@ function walkDirMd(dir) {
       const full = path.join(d, name)
       try {
         if (fs.statSync(full).isDirectory()) { walk(full) }
-        else if (name.endsWith('.md')) { results.push(name) }
+        else if (name.endsWith('.md')) { results.push({ name, fullPath: full }) }
       } catch (_) {}
     }
   }
-  walk(dir)
+  walk(expandedDir)
   return results
 }
 
+// walkDirMd retorna basenames de todos .md recursivamente dentro de dir.
+function walkDirMd(dir) {
+  return walkDirMdWithPaths(dir).map(item => item.name)
+}
+
 // findAdrFile busca o basename recursivamente em todos os adrDirs configurados.
 // Retorna o caminho completo se encontrado, ou null.
 function findAdrFile(basename) {
   const cfg = config.load()
-  for (const adrDir of cfg.adrDirs) {
+  const adrDirs = (cfg.adrDirs || []).map(d => config.expandPath ? config.expandPath(d) : d)
+  for (const adrDir of adrDirs) {
     function search(d) {
       let entries
       try { entries = fs.readdirSync(d) } catch (_) { return null }
@@ -260,12 +275,45 @@ function validateREQsHaveRoadmap() {
   return violations
 }
 
-// validateADRsAreReferenced — ADRs em adrDirs não referenciados em nenhuma REQ → violation
+// validateADRDirsExist — verifica se todos adrDirs existem.
+// Retorna { violations: [], warnings: [] } respeitando strictCiPaths.
+function validateADRDirsExist() {
+  const cfg = config.load()
+  const violations = []
+  const warnings = []
+  for (const adrDir of cfg.adrDirs || []) {
+    const expanded = config.expandPath ? config.expandPath(adrDir) : adrDir
+    const absDir = path.resolve(expanded)
+    if (!fs.existsSync(absDir)) {
+      const msg = `adr directory "${adrDir}" does not exist`
+      if (cfg.strictCiPaths) {
+        violations.push(msg)
+      } else {
+        warnings.push(msg)
+      }
+    }
+  }
+  return { violations, warnings }
+}
+
+// validateADRsAreReferenced — ADRs em adrDirs não referenciados em nenhuma REQ → violation.
+// ADRs localizados fora do projeto local (cwd) são isentos desta validação.
 function validateADRsAreReferenced() {
   const cfg = config.load()
+  const cwd = process.cwd()
   let adrs = []
-  for (const adrDir of cfg.adrDirs) {
-    adrs = adrs.concat(walkDirMd(adrDir))
+  for (const adrDir of cfg.adrDirs || []) {
+    const expanded = config.expandPath ? config.expandPath(adrDir) : adrDir
+    const absDir = path.resolve(expanded)
+    // Isentar diretórios fora do cwd local
+    if (!isInsideDir(cwd, absDir)) {
+      continue
+    }
+    for (const item of walkDirMdWithPaths(absDir)) {
+      if (isInsideDir(cwd, item.fullPath)) {
+        adrs.push(item.name)
+      }
+    }
   }
 
   const reqFiles = resolveReqFiles(cfg)
@@ -633,10 +681,12 @@ function validateRefTargetsExist() {
 }
 
 function referenceExists(ref, roots) {
-  if (fs.existsSync(ref)) return true
+  const expandedRef = config.expandPath ? config.expandPath(ref) : ref
+  if (fs.existsSync(expandedRef)) return true
   const basename = path.basename(ref)
   for (const root of roots || []) {
-    if (walkDirMd(root).some(filePath => path.basename(filePath) === basename)) return true
+    const expandedRoot = config.expandPath ? config.expandPath(root) : root
+    if (walkDirMd(expandedRoot).some(filePath => path.basename(filePath) === basename)) return true
   }
   return false
 }
@@ -884,6 +934,11 @@ async function validateUnfiltered() {
   // Regra direta (sem configuração de severidade): violation sempre
   for (const msg of validateFrontmatterPresence())  { _setMeta(msg, 'frontmatter_presence'); violations.push(msg) }
 
+  // Validação de existência dos adr_dirs (retorna violations se strictCiPaths, senão warnings)
+  const adrDirsExistResult = validateADRDirsExist()
+  for (const msg of adrDirsExistResult.violations) { _setMeta(msg, 'adr_dirs_exist'); violations.push(msg) }
+  for (const msg of adrDirsExistResult.warnings) { _setMeta(msg, 'adr_dirs_exist'); warnings.push(msg) }
+
   // warnings diretos do WIP limit (não configuráveis)
   for (const msg of wipLimitResult.warnings) { _setMeta(msg, 'wip_limit'); warnings.push(msg) }
 
@@ -1045,4 +1100,8 @@ module.exports = {
   // novas funções ML-1B (v2.5.1)
   getItemMeta,
   resetMeta,
+  // novas funções ML-2B (governança global)
+  isInsideDir,
+  walkDirMdWithPaths,
+  validateADRDirsExist,
 }