trackfw 2.12.0 → 2.12.3

package/README.md

@@ -3,7 +3,7 @@
 > The AI-native governance layer for software delivery — ADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned
 
 [![Release](https://img.shields.io/github/v/release/kgsaran/trackfw)](https://github.com/kgsaran/trackfw/releases/latest)
-[![Go](https://img.shields.io/badge/go-1.21+-00ADD8?logo=go)](go.mod)
+[![Go](https://img.shields.io/badge/go-1.25+-00ADD8?logo=go)](go.mod)
 [![npm](https://img.shields.io/npm/v/trackfw?logo=npm&color=CB3837)](https://www.npmjs.com/package/trackfw)
 [![PyPI](https://img.shields.io/pypi/v/trackfw?logo=python&color=3776AB)](https://pypi.org/project/trackfw/)
 [![License](https://img.shields.io/github/license/kgsaran/trackfw)](LICENSE)
@@ -90,7 +90,9 @@ go install github.com/kgsaran/trackfw/cmd/trackfw@latest
 npm install -g trackfw
 ```
 
-The npm package is pure Node.js — no compiled binary, no postinstall download. Works everywhere Node.js ≥ 18 is installed, including corporate Windows environments where unsigned `.exe` files are blocked by antivirus. Full feature parity with the Go CLI — all commands, all validation rules, all by_agent features.
+The npm package is pure Node.js — no compiled binary or postinstall download.
+It works wherever Node.js ≥ 18 is installed. Shared behavior and intentional
+Go-only integration installers follow the [CLI parity contract](docs/cli-parity.md).
 
 ### pip
 
@@ -98,7 +100,9 @@ The npm package is pure Node.js — no compiled binary, no postinstall download.
 pip install trackfw
 ```
 
-The pip package is pure Python — no compiled binary, no postinstall download. Full feature parity with the Go CLI — all commands, all validation rules, all by_agent features.
+The pip package is pure Python 3.10+ — no compiled binary or postinstall
+download. Shared commands, validation rules, and by_agent behavior follow the
+[CLI parity contract](docs/cli-parity.md).
 
 ---
 
@@ -323,6 +327,7 @@ $ trackfw status
 
 | Command | Installs | Format |
 |---|---|---|
+| `trackfw init --ai-tools codex` | `AGENTS.md`, 5 repository skills, 6 custom agents, Codex config and hooks | `.agents/skills/` + `.codex/` |
 | `trackfw agents` | 10 subagents in `~/.claude/agents/` | Claude Code `.md` with frontmatter |
 | `trackfw gemini` | GEMINI.md + 10 skills + 3 commands | `~/.gemini/` + project root |
 | `trackfw cursor` | 10 rules in `.cursor/rules/` | `.mdc` with YAML frontmatter |
@@ -345,11 +350,13 @@ The 10 roles installed for each tool: **architect · backend · frontend · qa
 ? Package manager?       npm / pnpm / yarn / bun
 ? Git hooks?             husky / lefthook / none
 ? CI system?             GitHub Actions / GitLab CI / none
-? Which AI assistants?   Claude Code / Gemini CLI / Cursor / Copilot / Windsurf / Amazon Q
+? Which AI assistants?   Claude Code / OpenAI Codex / Gemini CLI / Cursor / Copilot / Windsurf / Amazon Q
 ```
 
 The governance structure (`docs/adr/`, `docs/req/`, `docs/roadmaps/`) is always identical — stack-agnostic. The generated hooks, workflows, and AI integrations adapt to your answers.
 
+The Codex integration is repository-scoped: `AGENTS.md` carries persistent instructions, `.agents/skills/` provides governance workflows, `.codex/agents/` provides specialist subagents, and `.codex/hooks.json` signals permission requests to the local dashboard.
+
 ---
 
 ## Design principles
@@ -374,6 +381,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.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).",
+  "version": "2.12.3",
+  "description": "Governance CLI for AI-native software delivery. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, and Amazon Q.",
   "keywords": [
     "cli",
     "adr",
@@ -13,6 +13,17 @@
     "ai-agents",
     "developer-tools",
     "kanban",
+    "traceability",
+    "software-governance",
+    "ai-governance",
+    "pre-commit",
+    "developer-experience",
+    "technical-debt",
+    "claude-code",
+    "openai-codex",
+    "gemini",
+    "cursor",
+    "copilot",
     "req",
     "trackfw"
   ],
@@ -30,6 +41,10 @@
     "bin/",
     "src/"
   ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "smoke": "node bin/trackfw --help && node bin/trackfw version"
+  },
   "dependencies": {
     "commander": "^12.0.0",
     "@inquirer/prompts": "^5.0.0"

package/src/commands/index.js

@@ -26,6 +26,7 @@ function createProgram() {
   program.addCommand(require('./baseline'))
   program.addCommand(require('./help'))
   program.addCommand(require('./configure'))
+  program.addCommand(require('./version'))
 
   const { createServeCommand } = require('./serve')
   program.addCommand(createServeCommand())

package/src/commands/init.js

@@ -4,7 +4,8 @@ const { t } = require('../i18n')
 
 const cmd = new Command('init')
 cmd.description(t('init.description'))
-cmd.action(async () => {
+cmd.option('--ai-tools <tools>', 'Comma-separated AI tools to configure (codex,claude,gemini,cursor,copilot,windsurf,amazonq)', '')
+cmd.action(async (options) => {
   const path = require('path')
   const generators = require('../generators/init')
 
@@ -20,6 +21,19 @@ cmd.action(async () => {
       ci: 'none',
     }
     await generators.scaffold(cfg)
+    const aiTools = String(options.aiTools || '').split(',').map(tool => tool.trim()).filter(Boolean)
+    for (const tool of aiTools) {
+      switch (tool) {
+        case 'codex':    require('../generators/codex').installCodex(process.cwd()); break
+        case 'claude':   await generators.installAgents();  break
+        case 'gemini':   await generators.installGemini();  break
+        case 'cursor':   await generators.installCursor();  break
+        case 'copilot':  await generators.installCopilot(); break
+        case 'windsurf': await generators.installWindsurf(); break
+        case 'amazonq':  await generators.installAmazonQ(); break
+        default: throw new Error(`Unsupported AI tool: ${tool}`)
+      }
+    }
     console.log(`\n${t('init.success')}`)
     require('../generators/init').printArchitectNextSteps(process.cwd())
     return
@@ -141,6 +155,7 @@ cmd.action(async () => {
       message: t('init.prompt.aiTools'),
       choices: [
         { name: 'Claude Code', value: 'claude' },
+        { name: 'OpenAI Codex', value: 'codex' },
         { name: 'Gemini CLI', value: 'gemini' },
         { name: 'Cursor', value: 'cursor' },
         { name: 'GitHub Copilot', value: 'copilot' },
@@ -170,6 +185,7 @@ cmd.action(async () => {
 
   for (const tool of (aiTools || [])) {
     switch (tool) {
+      case 'codex':    require('../generators/codex').installCodex(process.cwd()); break
       case 'claude':   await generators.installAgents();  break
       case 'gemini':   await generators.installGemini();  break
       case 'cursor':   await generators.installCursor();  break

package/src/commands/plugins.js

@@ -7,6 +7,8 @@ const https = require('https')
 const { t } = require('../i18n')
 
 const REGISTRY_URL = 'https://raw.githubusercontent.com/kgsaran/trackfw-plugins/main/registry.yaml'
+const MAX_PLUGIN_SIZE = 50 * 1024 * 1024
+const REQUEST_TIMEOUT_MS = 30000
 
 function fetchRegistry() {
   return new Promise((resolve, reject) => {
@@ -91,15 +93,27 @@ async function installPlugin(repo) {
     ? `https://github.com/${base}/releases/latest/download/${assetName}`
     : `https://github.com/${base}/releases/download/${tag}/${assetName}`
 
-  const res = await fetch(url)
+  const res = await fetch(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) })
   if (!res.ok) throw new Error(t('errors.downloadFailed', { status: res.status, url }))
+  const declaredSize = Number(res.headers.get('content-length') || 0)
+  if (declaredSize > MAX_PLUGIN_SIZE) throw new Error(`Plugin exceeds ${MAX_PLUGIN_SIZE} bytes`)
 
   const dir = pluginsDir()
   fs.mkdirSync(dir, { recursive: true })
-  fs.writeFileSync(path.join(dir, pluginName), Buffer.from(await res.arrayBuffer()), { mode: 0o755 })
+  const content = Buffer.from(await res.arrayBuffer())
+  if (content.length > MAX_PLUGIN_SIZE) throw new Error(`Plugin exceeds ${MAX_PLUGIN_SIZE} bytes`)
+  const destination = path.join(dir, pluginName)
+  const temporary = path.join(dir, `.${pluginName}-${process.pid}.tmp`)
+  try {
+    fs.writeFileSync(temporary, content, { mode: 0o755 })
+    fs.renameSync(temporary, destination)
+  } finally {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary)
+  }
 }
 
 function removePlugin(name) {
+  if (!name || path.basename(name) !== name) throw new Error(`Invalid plugin name: ${name}`)
   const filePath = path.join(pluginsDir(), name)
   if (!fs.existsSync(filePath)) throw new Error(t('errors.pluginNotFound', { name }))
   fs.unlinkSync(filePath)

package/src/commands/serve.js

@@ -9,6 +9,7 @@ const { handleBoard } = require('../serve/api_board')
 const { handleChain } = require('../serve/api_chain')
 const { handleMetrics } = require('../serve/api_metrics')
 const { handleFile } = require('../serve/api_file')
+const { handleAttention } = require('../serve/api_attention')
 
 const STATIC_DIR = path.join(__dirname, '..', 'serve', 'static')
 
@@ -121,6 +122,11 @@ function createServer(cfg, port) {
       return
     }
 
+    if (pathname === '/api/attention') {
+      handleAttention(cfg, req, res)
+      return
+    }
+
     res.writeHead(404, { 'Content-Type': 'text/plain' })
     res.end('Not found')
   })

package/src/commands/update.js

@@ -71,6 +71,13 @@ cmd.action(() => {
   } catch (e) {
     console.log(`  ⚠ agent rules: ${e.message}`);
   }
+  if (fs.existsSync(path.join(cwd, 'AGENTS.md')) || fs.existsSync(path.join(cwd, '.codex'))) {
+    try {
+      require('../generators/codex').installCodex(cwd);
+    } catch (e) {
+      console.warn(`  ⚠ Codex integration: ${e.message}`);
+    }
+  }
 
   // 1b. Agent hooks (attention signal/cleanup)
   try {

package/src/commands/version.js

@@ -0,0 +1,10 @@
+'use strict'
+
+const { Command } = require('commander')
+const { version } = require('../../package.json')
+
+module.exports = new Command('version')
+  .description('Print version')
+  .action(() => {
+    console.log(`trackfw ${version}`)
+  })

package/src/generators/codex.js

@@ -0,0 +1,111 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { injectCodexHooks } = require('./hooks')
+const { injectRulesForTool } = require('./init')
+
+const skills = {
+  'trackfw-governance': `---
+name: trackfw-governance
+description: Inspect or maintain ADR, REQ, ROADMAP, traceability, lifecycle state, and trackfw validation. Use for governance questions and artifact changes.
+---
+Run \`trackfw context --format=json\`, preserve the ADR → REQ → ROADMAP chain, and finish with \`trackfw validate --json\`.
+`,
+  'trackfw-plan': `---
+name: trackfw-plan
+description: Plan a trackfw-governed implementation before code changes. Use for ADRs, REQs, roadmaps, microbatches, acceptance criteria, and validation commands.
+---
+Inspect existing artifacts and code. Create required decisions and requirements before a decision-complete roadmap. Keep the roadmap in analyzing until coding starts.
+`,
+  'trackfw-implement': `---
+name: trackfw-implement
+description: Implement work governed by an existing trackfw roadmap. Use for features and fixes that must follow lifecycle and validation gates.
+---
+Identify the matching REQ and roadmap, move it to wip, implement one microbatch at a time, run project tests and \`trackfw validate --json\`, then update lifecycle state.
+`,
+  'trackfw-review': `---
+name: trackfw-review
+description: Review a change for governance traceability, correctness, security, regressions, missing tests, and roadmap acceptance.
+---
+Stay read-only unless fixes are requested. Report evidence-backed findings by severity and verify the linked REQ, roadmap, acceptance criteria, tests, and validation output.
+`,
+  'trackfw-release': `---
+name: trackfw-release
+description: Prepare and verify a trackfw release. Use for versioning, changelog, packaging, parity, and publication gates.
+---
+Run all quality and parity gates, derive SemVer from commits, and stop before tags or publication unless explicitly authorized.
+`,
+}
+
+const agents = {
+  'trackfw-architect.toml': `name = "trackfw_architect"
+description = "Architecture and implementation-planning specialist for governed changes."
+sandbox_mode = "read-only"
+developer_instructions = """
+Map architecture, contracts, constraints, and traceability. Require ADRs for unresolved material decisions. Produce decision-complete plans and do not edit files unless explicitly assigned.
+"""
+`,
+  'trackfw-backend.toml': `name = "trackfw_backend"
+description = "Backend implementation specialist for APIs, domain logic, integrations, Go, Java, Node.js, and Python."
+developer_instructions = """
+Implement only the assigned backend scope, preserve contracts and traceability, run focused tests, and report changed files and evidence.
+"""
+`,
+  'trackfw-frontend.toml': `name = "trackfw_frontend"
+description = "Frontend implementation specialist focused on accessibility, i18n, UX consistency, and browser behavior."
+developer_instructions = """
+Implement only the assigned frontend scope, preserve accessibility and localization, and run focused build and UI tests.
+"""
+`,
+  'trackfw-qa.toml': `name = "trackfw_qa"
+description = "Read-only QA specialist for regressions, flaky tests, critical flows, and acceptance coverage."
+sandbox_mode = "read-only"
+developer_instructions = """
+Trace critical flows and compare behavior against roadmap acceptance criteria. Report reproducible failures and test gaps.
+"""
+`,
+  'trackfw-security.toml': `name = "trackfw_security"
+description = "Read-only security reviewer for trust boundaries, secrets, injection, permissions, and unsafe defaults."
+sandbox_mode = "read-only"
+developer_instructions = """
+Perform evidence-backed threat analysis. Report concrete exploit paths and mitigations by severity.
+"""
+`,
+  'trackfw-reviewer.toml': `name = "trackfw_reviewer"
+description = "Owner-level reviewer for correctness, governance, maintainability, security, and missing tests."
+sandbox_mode = "read-only"
+developer_instructions = """
+Review the branch as an owner. Return findings first, ordered by severity, with file references and governance evidence.
+"""
+`,
+}
+
+function writeManaged(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, content.trim() + '\n', 'utf8')
+}
+
+function installCodex(cwd) {
+  const root = cwd || process.cwd()
+  injectRulesForTool('codex', root)
+
+  const configPath = path.join(root, '.codex', 'config.toml')
+  fs.mkdirSync(path.dirname(configPath), { recursive: true })
+  let config = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : ''
+  if (!/^\[agents\]\s*$/m.test(config)) {
+    config = config.replace(/\s*$/, '') + '\n\n[agents]\nmax_threads = 6\nmax_depth = 1\n'
+    fs.writeFileSync(configPath, config, 'utf8')
+  }
+
+  for (const [name, content] of Object.entries(skills)) {
+    writeManaged(path.join(root, '.agents', 'skills', name, 'SKILL.md'), content)
+  }
+  for (const [name, content] of Object.entries(agents)) {
+    writeManaged(path.join(root, '.codex', 'agents', name), content)
+  }
+  injectCodexHooks(root)
+  console.log('  ✓ Codex: AGENTS.md, skills, custom agents and hooks')
+}
+
+module.exports = { installCodex }

package/src/generators/hooks.js

@@ -33,19 +33,21 @@ function hasEntry(arr, field, value) {
 // ---------------------------------------------------------------------------
 
 const SIGNAL_SCRIPT = `#!/usr/bin/env bash
-# trackfw attention signal — PreToolUse/BeforeTool hook
+# trackfw attention signal — permission/notification hook
 # Writes .trackfw-attention.json so trackfw serve board shows a banner.
 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"
 [ -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]')
+  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]')
 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")
+  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")
 fi
 
 ROADMAP_DIR=$(grep '^roadmap_dir:' trackfw.yaml 2>/dev/null | awk '{print $2}' | tr -d "\"'" | head -1)
@@ -66,6 +68,9 @@ 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"
 [ -f "trackfw.yaml" ] || exit 0
 
 ROADMAP_DIR=$(grep '^roadmap_dir:' trackfw.yaml 2>/dev/null | awk '{print $2}' | tr -d "\"'" | head -1)
@@ -142,14 +147,24 @@ 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 (!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 (!hasEntry(data.PostToolUse, 'command', CLEANUP_CMD)) {
-    data.PostToolUse.push({ matcher: '.*', command: CLEANUP_CMD })
+  if (!hasNestedCommand(data.hooks.PostToolUse, CLEANUP_CMD)) {
+    data.hooks.PostToolUse.push({
+      matcher: '.*',
+      hooks: [{ type: 'command', command: CLEANUP_CMD, timeout: 10 }],
+    })
   }
 
   writeJSON(filePath, data)
@@ -165,14 +180,25 @@ function injectGeminiHooks(cwd) {
 
   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.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 (!hasEntry(data.hooks.AfterTool, 'command', CLEANUP_CMD)) {
-    data.hooks.AfterTool.push({ command: CLEANUP_CMD })
+  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 }],
+    })
   }
 
   writeJSON(filePath, data)
@@ -210,10 +236,11 @@ function injectKiroHooks(cwd) {
 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 },
-    ],
+    version: 1,
+    hooks: {
+      preToolUse: [{ type: 'command', bash: SIGNAL_CMD, cwd: '.', timeoutSec: 10 }],
+      postToolUse: [{ type: 'command', bash: CLEANUP_CMD, cwd: '.', timeoutSec: 10 }],
+    },
   }
   writeJSON(filePath, data)
 }

package/src/generators/init.js

@@ -104,7 +104,7 @@ trackfw validate
       break
     }
     case 'python':
-      base += "echo \"→ build check (python)...\"\npython -m py_compile $(find . -name '*.py' -not -path './.venv/*' -not -path './venv/*')\n"
+      base += "echo \"→ build check (python)...\"\npython3 -c \"import pathlib, py_compile; [py_compile.compile(str(p), doraise=True) for p in pathlib.Path('.').rglob('*.py') if '.venv' not in p.parts and 'venv' not in p.parts]\"\n"
       break
   }
 
@@ -583,7 +583,7 @@ function backendCommands(cfg) {
       return [`${pm} run build`, `${pm} test`, `${pm} run lint`]
     case 'python':
       return [
-        "python -m py_compile $(find . -name '*.py' -not -path './.venv/*' -not -path './venv/*')",
+        "python3 -c \"import pathlib, py_compile; [py_compile.compile(str(p), doraise=True) for p in pathlib.Path('.').rglob('*.py') if '.venv' not in p.parts and 'venv' not in p.parts]\"",
         'python -m pytest',
         'ruff check .',
       ]
@@ -941,45 +941,45 @@ async function installAgents() {
   console.log('  ✓ claude (agentes — execute `trackfw install agents` com o binário Go para instalar os templates)')
 }
 
-async function installGemini() {
+async function installGemini(cwd = process.cwd()) {
   try {
-    injectRulesForTool('gemini', process.cwd())
+    injectRulesForTool('gemini', cwd)
     console.log('  ✓ trackfw rules → GEMINI.md')
   } catch (e) {
     console.log(`  ⚠ gemini rules inject: ${e.message}`)
   }
 }
 
-async function installCursor() {
+async function installCursor(cwd = process.cwd()) {
   try {
-    injectRulesForTool('cursor', process.cwd())
+    injectRulesForTool('cursor', cwd)
     console.log('  ✓ trackfw rules → .cursor/rules/trackfw.mdc')
   } catch (e) {
     console.log(`  ⚠ cursor rules inject: ${e.message}`)
   }
 }
 
-async function installCopilot() {
+async function installCopilot(cwd = process.cwd()) {
   try {
-    injectRulesForTool('copilot', process.cwd())
+    injectRulesForTool('copilot', cwd)
     console.log('  ✓ trackfw rules → .github/copilot-instructions.md')
   } catch (e) {
     console.log(`  ⚠ copilot rules inject: ${e.message}`)
   }
 }
 
-async function installWindsurf() {
+async function installWindsurf(cwd = process.cwd()) {
   try {
-    injectRulesForTool('windsurf', process.cwd())
+    injectRulesForTool('windsurf', cwd)
     console.log('  ✓ trackfw rules → .windsurfrules')
   } catch (e) {
     console.log(`  ⚠ windsurf rules inject: ${e.message}`)
   }
 }
 
-async function installAmazonQ() {
+async function installAmazonQ(cwd = process.cwd()) {
   try {
-    injectRulesForTool('amazonq', process.cwd())
+    injectRulesForTool('amazonq', cwd)
     console.log('  ✓ trackfw rules → .amazonq/developer/guidelines.md')
   } catch (e) {
     console.log(`  ⚠ amazonq rules inject: ${e.message}`)

package/src/serve/api_attention.js

@@ -0,0 +1,24 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+function getAttention(cfg) {
+  const attentionPath = path.join(cfg.roadmapDir, '.trackfw-attention.json')
+  try {
+    const payload = JSON.parse(fs.readFileSync(attentionPath, 'utf8'))
+    return { ...payload, active: true }
+  } catch (_) {
+    return { active: false }
+  }
+}
+
+function handleAttention(cfg, req, res) {
+  res.writeHead(200, {
+    'Content-Type': 'application/json',
+    'Access-Control-Allow-Origin': '*'
+  })
+  res.end(JSON.stringify(getAttention(cfg)))
+}
+
+module.exports = { getAttention, handleAttention }

package/src/serve/static/app.js

@@ -14,10 +14,20 @@ let _burnChart   = null;     // instância Chart.js burndown
 let _d3Sim       = null;     // simulação D3 force
 let _drawerPath  = null;     // path atualmente aberto no drawer
 
+// ─── Auto-refresh ─────────────────────────────────────────────────────────────
+let _refreshInterval = parseInt(localStorage.getItem('trackfw_refresh_interval') || '60');
+let _refreshPaused   = localStorage.getItem('trackfw_refresh_paused') === 'true';
+let _refreshTimer    = null;
+
+// ─── Atenção de agente ────────────────────────────────────────────────────────
+let _attentionTimer     = null;
+let _attentionDismissed = localStorage.getItem('trackfw_attention_dismissed') || null;
+
 // Cores canonicas por estado
 const STATE_COLORS = {
   wip:       '#3b82f6',
   backlog:   '#6b7280',
+  analyzing: '#f59e0b',
   blocked:   '#ef4444',
   done:      '#22c55e',
   abandoned: '#78716c',
@@ -39,7 +49,7 @@ function truncate(str, max = 30) {
 
 function stateLabel(state) {
   const labels = {
-    wip: 'WIP', backlog: 'BACKLOG', blocked: 'BLOCKED', done: 'DONE', abandoned: 'ABANDONED',
+    wip: 'WIP', backlog: 'BACKLOG', analyzing: 'Analisando', blocked: 'BLOCKED', done: 'DONE', abandoned: 'ABANDONED',
   };
   return labels[state] || state.toUpperCase();
 }
@@ -93,9 +103,9 @@ function switchView(view) {
 
 // ─── View: Board / Kanban ─────────────────────────────────────────────────────
 
-const COLUMNS_ORDER = ['backlog', 'wip', 'blocked', 'done', 'abandoned'];
+const COLUMNS_ORDER = ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned'];
 const COLUMNS_LABEL = {
-  wip: 'WIP', backlog: 'Backlog', blocked: 'Blocked', done: 'Done', abandoned: 'Abandoned',
+  wip: 'WIP', backlog: 'Backlog', analyzing: 'Analisando', blocked: 'Blocked', done: 'Done', abandoned: 'Abandoned',
 };
 
 async function loadBoard() {
@@ -162,6 +172,9 @@ function renderBoard(data, agentFilter) {
     if (agentFilter) {
       cards = cards.filter(c => c.agent === agentFilter);
     }
+    if (state === 'wip') {
+      cards = [...cards].sort((a, b) => (b.active_ml ? 1 : 0) - (a.active_ml ? 1 : 0));
+    }
 
     const col = document.createElement('div');
     col.className = 'kanban-column bg-white rounded-lg border border-gray-200 shadow-sm flex flex-col';
@@ -197,18 +210,52 @@ function renderBoard(data, agentFilter) {
 }
 
 function createCard(card) {
+  const isActive = !!(card.active_ml) && card.state === 'wip';
+
   const div = document.createElement('div');
-  div.className = 'kanban-card bg-gray-50 border border-gray-200 rounded-md p-3 hover:bg-white';
+  div.className = `kanban-card bg-gray-50 border border-gray-200 rounded-md p-3 hover:bg-white${isActive ? ' card-active' : ''}`;
   div.setAttribute('tabindex', '0');
   div.setAttribute('role', 'button');
   div.setAttribute('aria-label', `Abrir: ${card.title || card.file}`);
+  div.setAttribute('data-file', card.file || '');
+
+  const total    = card.ml_total  || 0;
+  const done     = card.ml_done   || 0;
+  const activeML = card.active_ml || '';
+  const nextML   = card.next_ml   || '';
+  const pct      = total > 0 ? Math.round((done / total) * 100) : 0;
+
+  let barColor = 'bg-blue-500';
+  if (card.state === 'blocked') barColor = 'bg-red-400';
+  else if (done === total && total > 0) barColor = 'bg-green-500';
+
+  const mlLabel = activeML
+    ? `<p class="text-xs text-blue-600 mt-1 leading-snug truncate" title="${escapeHtml(activeML)}">▶ ${escapeHtml(activeML)}</p>`
+    : nextML
+      ? `<p class="text-xs text-gray-400 mt-1 leading-snug truncate" title="${escapeHtml(nextML)}">→ ${escapeHtml(nextML)}</p>`
+      : '';
+
+  const progressHTML = total > 0 ? `
+    <div class="mt-2 pt-2 border-t border-gray-100">
+      <div class="flex items-center justify-between mb-1">
+        <span class="text-xs text-gray-400">MLs</span>
+        <span class="text-xs font-medium text-gray-600">${done}/${total}</span>
+      </div>
+      <div class="w-full bg-gray-200 rounded-full h-1.5">
+        <div class="${barColor} h-1.5 rounded-full transition-all" style="width:${pct}%"></div>
+      </div>
+      ${mlLabel}
+    </div>` : '';
 
   div.innerHTML = `
+    ${isActive ? '<span class="live-dot" aria-hidden="true"></span>' : ''}
     <p class="text-xs font-semibold text-gray-800 mb-2 leading-snug">${escapeHtml(card.title || card.file)}</p>
     <div class="flex flex-wrap items-center gap-1">
       ${card.agent ? `<span class="inline-block text-xs bg-purple-100 text-purple-700 px-1.5 py-0.5 rounded font-medium">${escapeHtml(card.agent)}</span>` : ''}
       <span class="badge-${card.state} inline-block text-xs px-1.5 py-0.5 rounded font-medium">${stateLabel(card.state)}</span>
-    </div>`;
+      ${isActive ? '<span class="inline-block text-xs bg-green-100 text-green-700 px-1.5 py-0.5 rounded font-medium">ATIVO</span>' : ''}
+    </div>
+    ${progressHTML}`;
 
   div.addEventListener('click', () => openDrawer(card.path));
   div.addEventListener('keydown', e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); openDrawer(card.path); } });
@@ -222,6 +269,144 @@ function filterByAgent(agent) {
   }
 }
 
+// ─── Auto-refresh ─────────────────────────────────────────────────────────────
+
+function startRefreshTimer() {
+  clearTimeout(_refreshTimer);
+  if (_refreshPaused || _refreshInterval <= 0) return;
+  _refreshTimer = setTimeout(() => {
+    if (_currentView === 'board') {
+      _boardData = null;
+      loadBoard();
+    }
+    startRefreshTimer();
+  }, _refreshInterval * 1000);
+}
+
+function setRefreshInterval(seconds) {
+  _refreshInterval = seconds;
+  localStorage.setItem('trackfw_refresh_interval', String(seconds));
+  startRefreshTimer();
+}
+
+function toggleRefreshPause() {
+  _refreshPaused = !_refreshPaused;
+  localStorage.setItem('trackfw_refresh_paused', String(_refreshPaused));
+  if (_refreshPaused) {
+    clearTimeout(_refreshTimer);
+  } else {
+    startRefreshTimer();
+  }
+  updateRefreshUI();
+}
+
+function manualRefresh() {
+  _boardData = null;
+  loadBoard();
+  startRefreshTimer();
+}
+
+function updateRefreshUI() {
+  const btn = el('refresh-toggle');
+  if (!btn) return;
+  btn.textContent = _refreshPaused ? '▶ Retomar' : '⏸ Pausar';
+}
+
+function initRefreshUI() {
+  const sel = el('refresh-interval');
+  if (sel) sel.value = String(_refreshInterval);
+  updateRefreshUI();
+}
+
+// ─── Atenção de agente ────────────────────────────────────────────────────────
+
+function startAttentionPolling() {
+  clearInterval(_attentionTimer);
+  _attentionTimer = setInterval(pollAttention, 8000);
+  pollAttention();
+}
+
+async function pollAttention() {
+  try {
+    const res = await fetch('/api/attention');
+    if (!res.ok) return;
+    const data = await res.json();
+    if (data.active && data.timestamp !== _attentionDismissed) {
+      showAttentionBanner(data);
+    } else if (!data.active) {
+      hideAttentionBanner();
+    }
+  } catch (_) { /* ignorar erros de rede */ }
+}
+
+function showAttentionBanner(data) {
+  const banner = el('attention-banner');
+  if (!banner) return;
+
+  const isAction = data.level !== 'info';
+  banner.className = `attention-banner ${isAction ? 'attention-banner-action' : 'attention-banner-info'}`;
+  banner.setAttribute('data-timestamp', data.timestamp || '');
+
+  const iconEl = el('attention-icon');
+  const labelEl = el('attention-label');
+  const ctxEl = el('attention-context');
+  const msgEl = el('attention-message');
+
+  if (iconEl)  iconEl.textContent  = isAction ? '⚠️' : 'ℹ️';
+  if (labelEl) labelEl.textContent = isAction ? 'Ação necessária' : 'Aviso';
+  if (ctxEl)   ctxEl.textContent   = [data.roadmap, data.ml].filter(Boolean).join(' · ');
+  if (msgEl)   msgEl.textContent   = data.message || '';
+
+  if (data.roadmap) markCardAttention(data.roadmap);
+}
+
+function hideAttentionBanner() {
+  const banner = el('attention-banner');
+  if (banner) banner.className = 'hidden attention-banner attention-banner-action';
+  clearCardAttention();
+}
+
+function dismissAttention() {
+  const banner = el('attention-banner');
+  if (!banner) return;
+  const ts = banner.getAttribute('data-timestamp');
+  if (ts) {
+    _attentionDismissed = ts;
+    localStorage.setItem('trackfw_attention_dismissed', ts);
+  }
+  hideAttentionBanner();
+}
+
+function markCardAttention(roadmapFile) {
+  document.querySelectorAll('.kanban-card[data-file]').forEach(c => {
+    if (c.getAttribute('data-file') !== roadmapFile) return;
+    c.classList.add('card-attention');
+    const live = c.querySelector('.live-dot');
+    if (live) {
+      live.className = 'attention-dot';
+    } else {
+      const dot = document.createElement('span');
+      dot.className = 'attention-dot';
+      dot.setAttribute('aria-hidden', 'true');
+      c.appendChild(dot);
+    }
+  });
+}
+
+function clearCardAttention() {
+  document.querySelectorAll('.card-attention').forEach(c => {
+    c.classList.remove('card-attention');
+    const dot = c.querySelector('.attention-dot');
+    if (dot) {
+      if (c.classList.contains('card-active')) {
+        dot.className = 'live-dot';
+      } else {
+        dot.remove();
+      }
+    }
+  });
+}
+
 // ─── View: Chain (D3 force-directed graph) ────────────────────────────────────
 
 async function loadChain() {
@@ -682,6 +867,8 @@ document.addEventListener('keydown', e => {
 // ─── Init ─────────────────────────────────────────────────────────────────────
 
 document.addEventListener('DOMContentLoaded', () => {
-  // Ativar tab Board e carregar dados iniciais
   switchView('board');
+  initRefreshUI();
+  startRefreshTimer();
+  startAttentionPolling();
 });

package/src/serve/static/index.html

@@ -43,23 +43,62 @@
     </nav>
   </header>
 
+  <!-- Banner de atenção de agente (visível apenas quando /api/attention retornar active:true) -->
+  <div id="attention-banner" class="hidden attention-banner attention-banner-action" role="alert" aria-live="assertive" aria-atomic="true">
+    <span id="attention-icon" aria-hidden="true">⚠️</span>
+    <span class="font-semibold" id="attention-label"></span>
+    <span class="opacity-80 font-mono text-xs" id="attention-context"></span>
+    <span class="mx-1 opacity-60">—</span>
+    <span id="attention-message" class="flex-1"></span>
+    <button onclick="dismissAttention()" class="ml-auto text-sm font-medium underline opacity-80 hover:opacity-100 whitespace-nowrap" aria-label="Dispensar alerta">✕ Dispensar</button>
+  </div>
+
   <!-- Conteúdo principal -->
   <main class="flex-1 relative overflow-hidden flex">
 
     <!-- View: Board -->
     <section id="view-board" class="view-section w-full p-6 overflow-auto" aria-label="Board kanban">
 
-      <!-- Filtro por agente -->
-      <div id="agent-filter-container" class="mb-4 hidden">
-        <label for="agent-filter" class="text-sm font-medium text-gray-600 mr-2">Filtrar por agente:</label>
-        <select
-          id="agent-filter"
-          onchange="filterByAgent(this.value)"
-          class="text-sm border border-gray-300 rounded px-2 py-1 bg-white"
-          aria-label="Filtrar roadmaps por agente"
-        >
-          <option value="">Todos</option>
-        </select>
+      <!-- Toolbar: filtro por agente + controles de auto-refresh -->
+      <div class="flex items-center gap-3 flex-wrap mb-4">
+        <div id="agent-filter-container" class="hidden">
+          <label for="agent-filter" class="text-sm font-medium text-gray-600 mr-2">Filtrar por agente:</label>
+          <select
+            id="agent-filter"
+            onchange="filterByAgent(this.value)"
+            class="text-sm border border-gray-300 rounded px-2 py-1 bg-white"
+            aria-label="Filtrar roadmaps por agente"
+          >
+            <option value="">Todos</option>
+          </select>
+        </div>
+        <!-- Auto-refresh controls -->
+        <div class="flex items-center gap-2 ml-auto">
+          <span class="text-xs text-gray-500">Auto-refresh:</span>
+          <select
+            id="refresh-interval"
+            onchange="setRefreshInterval(parseInt(this.value))"
+            class="text-xs border border-gray-300 rounded px-2 py-1 bg-white"
+            aria-label="Intervalo de atualização automática"
+          >
+            <option value="15">15s</option>
+            <option value="30">30s</option>
+            <option value="60">1 min</option>
+            <option value="120">2 min</option>
+            <option value="300">5 min</option>
+          </select>
+          <button
+            id="refresh-toggle"
+            onclick="toggleRefreshPause()"
+            class="text-xs bg-gray-100 text-gray-600 px-2 py-1 rounded hover:bg-gray-200 transition-colors"
+          >⏸ Pausar</button>
+          <button
+            onclick="manualRefresh()"
+            class="text-xs bg-gray-100 text-gray-600 px-2 py-1 rounded hover:bg-gray-200 transition-colors"
+            aria-label="Atualizar board agora"
+            title="Atualizar agora"
+          >↻</button>
+        </div>
       </div>
 
       <!-- Kanban columns -->

package/src/serve/static/style.css

@@ -36,6 +36,7 @@
 /* Cards kanban */
 .kanban-card {
   cursor: pointer;
+  position: relative;
   transition: box-shadow 0.15s ease, transform 0.1s ease;
 }
 
@@ -60,6 +61,11 @@
   color: #374151;
 }
 
+.badge-analyzing {
+  background-color: #fef3c7;
+  color: #92400e;
+}
+
 .badge-blocked {
   background-color: #fee2e2;
   color: #991b1b;
@@ -151,3 +157,62 @@
     width: 100% !important;
   }
 }
+
+/* ─── Live pulse — card ativo no WIP ─────────────────────────────────────── */
+@keyframes livePulse {
+  0%, 100% { opacity: 1;    transform: scale(1);    }
+  50%       { opacity: 0.3; transform: scale(0.65); }
+}
+
+.live-dot {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: #22c55e;
+  animation: livePulse 1.4s ease-in-out infinite;
+}
+
+.card-active {
+  border-left: 3px solid #22c55e !important;
+  background-color: #f0fdf4 !important;
+}
+.card-active:hover {
+  background-color: #dcfce7 !important;
+}
+
+/* ─── Atenção de agente ───────────────────────────────────────────────────── */
+@keyframes attentionRing {
+  0%, 100% { box-shadow: 0 0 0 0   rgba(245, 158, 11, 0.5); }
+  50%       { box-shadow: 0 0 0 8px rgba(245, 158, 11, 0);   }
+}
+
+.attention-dot {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: #f59e0b;
+  animation: livePulse 0.9s ease-in-out infinite;
+}
+
+.card-attention {
+  border-left: 3px solid #f59e0b !important;
+  animation: attentionRing 2s ease-in-out infinite;
+}
+
+/* Banner de atenção (entre header e main) */
+.attention-banner {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 24px;
+  font-size: 0.875rem;
+  line-height: 1.4;
+}
+.attention-banner-action { background-color: #f59e0b; color: #fff; }
+.attention-banner-info   { background-color: #3b82f6; color: #fff; }

package/src/validator/index.js

@@ -606,7 +606,7 @@ function validateRefTargetsExist() {
       try {
         const content = fs.readFileSync(path.join(dir, name), 'utf8')
         const ref = extractRefPath(content, 'REQ')
-        if (ref && !fs.existsSync(ref)) {
+        if (ref && !referenceExists(ref, [cfg.reqDir])) {
           warnings.push(`roadmap "${name}" links to REQ "${ref}" which does not exist`)
         }
       } catch (_) {}
@@ -619,11 +619,11 @@ function validateRefTargetsExist() {
       const content = fs.readFileSync(filePath, 'utf8')
       const name = path.basename(filePath)
       const adrRef = extractRefPath(content, 'ADR')
-      if (adrRef && !fs.existsSync(adrRef)) {
+      if (adrRef && !referenceExists(adrRef, cfg.adrDirs)) {
         warnings.push(`req "${name}" links to ADR "${adrRef}" which does not exist`)
       }
       const roadmapRef = extractRefPath(content, 'Roadmap')
-      if (roadmapRef && !fs.existsSync(roadmapRef)) {
+      if (roadmapRef && !referenceExists(roadmapRef, [cfg.roadmapDir])) {
         warnings.push(`req "${name}" links to Roadmap "${roadmapRef}" which does not exist`)
       }
     } catch (_) {}
@@ -632,6 +632,15 @@ function validateRefTargetsExist() {
   return warnings
 }
 
+function referenceExists(ref, roots) {
+  if (fs.existsSync(ref)) return true
+  const basename = path.basename(ref)
+  for (const root of roots || []) {
+    if (walkDirMd(root).some(filePath => path.basename(filePath) === basename)) return true
+  }
+  return false
+}
+
 // FOLDER_TO_STATUS mapeia pasta de estado para os valores válidos de status no frontmatter
 const FOLDER_TO_STATUS = {
   wip:       ['WIP', 'wip', 'In Progress'],
@@ -738,28 +747,49 @@ function validateFilenameUniqueness() {
 // 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
+  let branch = process.env.TRACKFW_BRANCH || ''
+  if (!branch && isGitWorktree(process.cwd())) {
+    try {
+      branch = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
+    } catch {
+      branch = ''
+    }
+    if (!branch) {
+      branch = process.env.GITHUB_HEAD_REF || process.env.CI_COMMIT_REF_NAME || process.env.GITHUB_REF_NAME || ''
+    }
   }
+  if (!branch) return []
   if (!branch.startsWith('feat/') && !branch.startsWith('fix/') && !branch.startsWith('refactor/')) {
     return []
   }
 
   const cfg = config.load()
   const wipDirs = resolveWIPDirs(cfg)
-  let total = 0
+  const branchSlug = normalizeBranchSlug(branch.split('/', 2)[1])
+  const wipFiles = []
   for (const wipDir of wipDirs) {
     const files = listDir(wipDir).filter(f => f.endsWith('.md'))
-    total += files.length
+    wipFiles.push(...files)
+    if (files.some(file => normalizeBranchSlug(file).includes(branchSlug))) return []
   }
 
-  if (total === 0) {
+  if (wipFiles.length === 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 []
+  return [`branch "${branch}" has no matching roadmap in wip/ (found: ${wipFiles.join(', ')}) — include the branch slug in the roadmap filename or set TRACKFW_BRANCH explicitly in CI`]
+}
+
+function normalizeBranchSlug(value) {
+  return String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+}
+
+function isGitWorktree(dir) {
+  try {
+    const out = execSync('git rev-parse --is-inside-work-tree', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], cwd: dir })
+    return String(out).trim() === 'true'
+  } catch {
+    return false
+  }
 }
 
 // _itemMeta: mapa de message → { rule, file } para enriquecer saída JSON.