trackfw 2.6.0 → 2.7.0

package/README.md

@@ -1,9 +1,11 @@
 # trackfw
 
-> Governed software delivery — ADR → REQ → ROADMAP → backlog / wip / done
+> 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)
+[![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)
 
 **trackfw** is an open-source CLI that enforces a traceable chain from architectural decision to shipped code — without SaaS, accounts, or databases. Markdown files are state.
@@ -23,6 +25,9 @@ Most teams accumulate technical debt not because they lack tools, but because th
 - **ADR tools** manage decision records, but don't connect them to delivery.
 - **Kanban tools** track tasks, but don't enforce that tasks are backed by a decision.
 - **CI tools** validate code, but don't validate governance.
+- **AI coding assistants** generate code at unprecedented speed, but without traceability: who decided what? Why? Which requirement authorized this roadmap?
+
+trackfw adds the governance layer that makes AI-assisted delivery auditable.
 
 trackfw closes the loop — connective tissue between *why*, *what*, and *when*.
 
@@ -85,7 +90,7 @@ 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.
+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.
 
 ### pip
 
@@ -93,6 +98,8 @@ 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.
+
 ---
 
 ## Quick start
@@ -133,6 +140,8 @@ trackfw status
 | `trackfw roadmap move <name> <state>` | Move roadmap between states |
 | `trackfw roadmap list` | List all roadmaps grouped by state |
 | `trackfw validate` | Check governance consistency (use as CI gate) |
+| `trackfw context` | Print a structured summary of the project's governance state (REQs, Roadmaps, ADRs with counts and statuses) |
+| `trackfw serve` | Start a local governance dashboard (no cloud, no accounts) |
 | `trackfw status` | Show wip, blocked, REQs waiting on ADRs |
 | `trackfw log [--tail N]` | Show roadmap state transition history |
 | `trackfw plugins list` | List installed plugins |
@@ -174,6 +183,60 @@ Moving a file between folders **is** the state transition. No database, no API.
 
 ---
 
+## AI-native governance
+
+trackfw v2.6.0 introduces features designed for teams where AI agents are first-class contributors.
+
+### Multi-agent namespacing
+
+```yaml
+# trackfw.yaml
+roadmap_namespacing: by_agent
+agents: [claude, gemini, copilot]
+```
+
+Artifacts are organized by agent: `docs/roadmaps/claude/wip/`, `docs/req/gemini/done/`. `trackfw validate` and `trackfw context` are fully by_agent-aware — no false positives.
+
+### Bidirectional traceability (`trace_id_field`)
+
+```yaml
+# trackfw.yaml
+trace_id_field: req_id
+```
+
+Automatically verifies the REQ↔ROADMAP link in both directions. Reports 5 check types:
+- `traceid_orphan_req` — REQ with no matching ROADMAP
+- `traceid_orphan_roadmap` — ROADMAP with no matching REQ
+- `traceid_state_mismatch` — REQ and ROADMAP in different states
+- `traceid_duplicate_req` / `traceid_duplicate_roadmap` — duplicate trace IDs
+
+### Configurable rules
+
+Every governance rule has configurable severity:
+
+```yaml
+# trackfw.yaml
+rules:
+  req_has_adr:      "error"    # default
+  req_has_roadmap:  "warning"  # relax for tactical REQs
+  blocked_has_req:  "error"
+  wip_limit:        "warning"
+  stale_wip:        "warning"
+  adr_orphan:       "off"      # silence during migration
+```
+
+15+ rules available. Adopt progressively — start with `warning`, tighten to `error` as your team builds the habit.
+
+### Governance gate
+
+```yaml
+# trackfw.yaml
+governance_mode: strict   # CI fails on any violation
+# governance_mode: lenient # CI passes with warnings only
+```
+
+---
+
 ## REQ-driven ADR discovery
 
 When you run `trackfw req new`, the wizard analyzes your intent and asks targeted questions for each detected domain — authentication, UI, persistence, API, deploy, events. Unanswered architectural decisions become ADR drafts automatically.
@@ -209,6 +272,26 @@ $ trackfw validate
 
 Designed to run as a **pre-commit hook** and a **CI quality gate**. `trackfw init` wires both automatically for your stack.
 
+### JSON output for CI integration
+
+```bash
+trackfw validate --json
+```
+
+```json
+{
+  "summary": { "violations": 2, "warnings": 1, "mode": "strict", "exit_code": 1 },
+  "violations": [
+    { "rule": "wip_has_req", "file": "roadmaps/wip/auth-service.md" }
+  ],
+  "warnings": [
+    { "rule": "stale_wip", "file": "roadmaps/wip/auth-service.md" }
+  ]
+}
+```
+
+Use `--json` for programmatic CI parsing, Slack notifications, or custom reporting.
+
 ---
 
 ## `trackfw status` — current state at a glance
@@ -277,12 +360,14 @@ The governance structure (`docs/adr/`, `docs/req/`, `docs/roadmaps/`) is always
 4. **One active roadmap at a time** — parallel work without traceability is the root of most delivery chaos.
 5. **Human-readable, machine-parseable** — every artifact is a Markdown file with a predictable structure.
 6. **Guided, not prescriptive** — the wizard surfaces decisions you might not know to ask; it never blocks work unnecessarily.
+7. **Configurable by design** — every governance rule has a severity (`off`/`warning`/`error`). Start permissive, tighten as your team builds the habit.
+8. **AI-agent aware** — `roadmap_namespacing: by_agent` and `trace_id_field` make AI-generated work traceable and auditable by default.
 
 ---
 
 ## What trackfw is not
 
-- Not a project management SaaS — no UI, no accounts, no cloud sync
+- Not a project management SaaS — no accounts, no cloud sync, no data leaving your repository. A local dashboard is available via `trackfw serve`.
 - Not a replacement for Git history — it complements, not duplicates
 - Not a task tracker — use GitHub Issues, Linear, or Jira for tasks; trackfw governs the *why*
 - Not opinionated about how you write code — only about how you document decisions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "2.6.0",
+  "version": "2.7.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/index.js

@@ -26,6 +26,9 @@ function createProgram() {
   program.addCommand(require('./help'))
   program.addCommand(require('./configure'))
 
+  const { createServeCommand } = require('./serve')
+  program.addCommand(createServeCommand())
+
   // plugin dispatch — comandos desconhecidos tentam executar plugin
   program.hook('preSubcommand', () => {})
 

package/src/commands/metrics.js

@@ -232,4 +232,11 @@ cmd.action((opts) => {
   }
 })
 
+// Exportar o comando como default para compatibilidade com index.js
+// e expor funções utilitárias para reutilização (ex: api_metrics.js do serve)
+cmd.parseLog = parseLog
+cmd.calculate = calculate
+
 module.exports = cmd
+module.exports.parseLog = parseLog
+module.exports.calculate = calculate

package/src/commands/serve.js

@@ -0,0 +1,184 @@
+'use strict'
+
+const http = require('http')
+const path = require('path')
+const fs = require('fs')
+const { Command } = require('commander')
+const config = require('../config')
+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 STATIC_DIR = path.join(__dirname, '..', 'serve', 'static')
+
+// Mapa de extensão → Content-Type
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js':   'application/javascript; charset=utf-8',
+  '.css':  'text/css; charset=utf-8',
+  '.json': 'application/json',
+  '.svg':  'image/svg+xml',
+  '.ico':  'image/x-icon',
+}
+
+/**
+ * serveStatic serve arquivos do STATIC_DIR.
+ * Retorna 404 se o arquivo não existe ou se o path tenta escape (path traversal).
+ * @param {string} urlPath - pathname da URL (ex: '/static/app.js')
+ * @param {http.ServerResponse} res
+ */
+function serveStatic(urlPath, res) {
+  // Remove o prefixo '/static'
+  const relative = urlPath.replace(/^\/static/, '') || '/index.html'
+  const resolved = path.resolve(path.join(STATIC_DIR, relative))
+
+  // Segurança: path traversal
+  if (!resolved.startsWith(path.resolve(STATIC_DIR) + path.sep) && resolved !== path.resolve(STATIC_DIR)) {
+    res.writeHead(403, { 'Content-Type': 'text/plain' })
+    res.end('Forbidden')
+    return
+  }
+
+  if (!fs.existsSync(resolved)) {
+    res.writeHead(404, { 'Content-Type': 'text/plain' })
+    res.end('Not Found')
+    return
+  }
+
+  const ext = path.extname(resolved).toLowerCase()
+  const contentType = MIME[ext] || 'application/octet-stream'
+
+  let content
+  try {
+    content = fs.readFileSync(resolved)
+  } catch (_) {
+    res.writeHead(500, { 'Content-Type': 'text/plain' })
+    res.end('Internal Server Error')
+    return
+  }
+
+  res.writeHead(200, { 'Content-Type': contentType })
+  res.end(content)
+}
+
+/**
+ * createServer cria o servidor HTTP do trackfw serve.
+ * @param {object} cfg - configuração do trackfw (resultado de config.load())
+ * @param {number} port
+ * @returns {http.Server}
+ */
+function createServer(cfg, port) {
+  return http.createServer((req, res) => {
+    // CORS permissivo para desenvolvimento local
+    res.setHeader('Access-Control-Allow-Origin', '*')
+
+    let urlObj
+    try {
+      urlObj = new URL(req.url, `http://localhost:${port}`)
+    } catch (_) {
+      res.writeHead(400)
+      res.end('Bad Request')
+      return
+    }
+
+    const pathname = urlObj.pathname
+
+    if (pathname === '/' || pathname === '/index.html') {
+      const indexPath = path.join(STATIC_DIR, 'index.html')
+      if (!fs.existsSync(indexPath)) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' })
+        res.end('index.html not found')
+        return
+      }
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+      res.end(fs.readFileSync(indexPath))
+      return
+    }
+
+    if (pathname.startsWith('/static/')) {
+      serveStatic(pathname, res)
+      return
+    }
+
+    if (pathname === '/api/board') {
+      handleBoard(cfg, req, res)
+      return
+    }
+
+    if (pathname === '/api/chain') {
+      handleChain(cfg, req, res)
+      return
+    }
+
+    if (pathname === '/api/metrics') {
+      handleMetrics(cfg, req, res)
+      return
+    }
+
+    if (pathname === '/api/file') {
+      handleFile(cfg, req, res)
+      return
+    }
+
+    res.writeHead(404, { 'Content-Type': 'text/plain' })
+    res.end('Not found')
+  })
+}
+
+/**
+ * createServeCommand retorna o comando commander 'serve'.
+ * @returns {Command}
+ */
+function createServeCommand() {
+  const cmd = new Command('serve')
+  cmd
+    .description('Inicia o servidor HTTP do trackfw dashboard (kanban + chain + metrics)')
+    .option('--port <port>', 'Porta do servidor', '8080')
+    .option('--no-open', 'Não abrir o browser automaticamente')
+    .action((opts) => {
+      const cfg = config.load()
+      const port = parseInt(opts.port, 10) || 8080
+
+      const server = createServer(cfg, port)
+
+      server.listen(port, '127.0.0.1', () => {
+        console.log(`trackfw serve: http://localhost:${port}`)
+
+        if (opts.open !== false) {
+          // Tentar abrir o browser
+          const url = `http://localhost:${port}`
+          const { exec } = require('child_process')
+          const platform = process.platform
+          let openCmd
+          if (platform === 'darwin') openCmd = `open "${url}"`
+          else if (platform === 'win32') openCmd = `start "" "${url}"`
+          else openCmd = `xdg-open "${url}"`
+          exec(openCmd, (err) => {
+            if (err) console.warn(`Não foi possível abrir o browser: ${err.message}`)
+          })
+        }
+      })
+
+      server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          console.error(`Porta ${port} já está em uso. Use --port para especificar outra.`)
+        } else {
+          console.error(`Erro no servidor: ${err.message}`)
+        }
+        process.exit(1)
+      })
+
+      // Graceful shutdown
+      process.on('SIGINT', () => {
+        server.close(() => {
+          console.log('\ntrackfw serve: encerrado.')
+          process.exit(0)
+        })
+      })
+    })
+
+  return cmd
+}
+
+module.exports = { createServeCommand, createServer }

package/src/serve/api_board.js

@@ -0,0 +1,104 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const STATES = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
+
+/**
+ * extractTitle retorna o título do arquivo: primeira linha '# ...' ou nome do arquivo sem extensão.
+ * @param {string} content
+ * @param {string} filename
+ * @returns {string}
+ */
+function extractTitle(content, filename) {
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed.startsWith('# ')) {
+      return trimmed.slice(2).trim()
+    }
+  }
+  return filename.replace(/\.md$/, '')
+}
+
+/**
+ * scanState lê todos os .md de um diretório e retorna os itens do kanban.
+ * @param {string} dir
+ * @param {string} state
+ * @param {string} agent - agente ou '' para flat
+ * @param {string} roadmapDir - diretório base (para montar path relativo)
+ * @returns {Array<{file: string, title: string, state: string, agent: string, path: string}>}
+ */
+function scanState(dir, state, agent, roadmapDir) {
+  const items = []
+  let files = []
+  try {
+    files = fs.readdirSync(dir).filter(f => {
+      if (!f.endsWith('.md')) return false
+      try { return !fs.statSync(path.join(dir, f)).isDirectory() } catch (_) { return false }
+    })
+  } catch (_) {
+    return items
+  }
+
+  for (const file of files) {
+    let content = ''
+    try { content = fs.readFileSync(path.join(dir, file), 'utf8') } catch (_) {}
+    const title = extractTitle(content, file)
+    const relPath = agent
+      ? path.join(roadmapDir, agent, state, file)
+      : path.join(roadmapDir, state, file)
+
+    items.push({ file, title, state, agent: agent || '', path: relPath })
+  }
+  return items
+}
+
+/**
+ * handleBoard responde ao GET /api/board com o kanban em JSON.
+ * @param {object} cfg - configuração do trackfw
+ * @param {http.IncomingMessage} req
+ * @param {http.ServerResponse} res
+ */
+function handleBoard(cfg, req, res) {
+  const roadmapDir = cfg.roadmapDir || 'docs/roadmaps'
+  const namespacing = cfg.roadmapNamespacing || 'flat'
+
+  const columns = { wip: [], backlog: [], blocked: [], done: [], abandoned: [] }
+  const agentSet = new Set()
+
+  if (namespacing === 'by_agent') {
+    let agents = cfg.agents || []
+    if (!agents.length) {
+      try {
+        agents = fs.readdirSync(roadmapDir).filter(f => {
+          try { return fs.statSync(path.join(roadmapDir, f)).isDirectory() } catch (_) { return false }
+        })
+      } catch (_) { agents = [] }
+    }
+    for (const agent of agents) {
+      agentSet.add(agent)
+      for (const state of STATES) {
+        const dir = path.join(roadmapDir, agent, state)
+        const items = scanState(dir, state, agent, roadmapDir)
+        columns[state].push(...items)
+      }
+    }
+  } else {
+    for (const state of STATES) {
+      const dir = path.join(roadmapDir, state)
+      const items = scanState(dir, state, '', roadmapDir)
+      columns[state].push(...items)
+    }
+  }
+
+  const result = {
+    columns,
+    agents: Array.from(agentSet).sort(),
+  }
+
+  res.writeHead(200, { 'Content-Type': 'application/json' })
+  res.end(JSON.stringify(result))
+}
+
+module.exports = { handleBoard }

package/src/serve/api_chain.js

@@ -0,0 +1,223 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const ROADMAP_STATES = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
+
+/**
+ * parseFrontmatter extrai todos os campos de um bloco frontmatter YAML (entre --- e ---).
+ * Retorna objeto com chaves/valores string.
+ * @param {string} content
+ * @returns {Object<string, string>}
+ */
+function parseFrontmatter(content) {
+  const fields = {}
+  const lines = content.split('\n')
+  let started = false
+  let inFm = false
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed === '---') {
+      if (!started) { started = true; inFm = true; continue }
+      break // fecha frontmatter
+    }
+    if (!inFm) break
+    const colonIdx = trimmed.indexOf(':')
+    if (colonIdx < 0) continue
+    const key = trimmed.slice(0, colonIdx).trim()
+    let val = trimmed.slice(colonIdx + 1).trim()
+    val = val.replace(/^["']|["']$/g, '')
+    if (key) fields[key] = val
+  }
+  return fields
+}
+
+/**
+ * extractTitle retorna a primeira linha '# ...' ou o nome do arquivo sem extensão.
+ * @param {string} content
+ * @param {string} filename
+ * @returns {string}
+ */
+function extractTitle(content, filename) {
+  for (const line of content.split('\n')) {
+    const t = line.trim()
+    if (t.startsWith('# ')) return t.slice(2).trim()
+  }
+  return filename.replace(/\.md$/, '')
+}
+
+/**
+ * collectNodes lê arquivos .md de um diretório e retorna nós do grafo.
+ * @param {string} dir
+ * @param {'adr'|'req'|'roadmap'} type
+ * @param {string} state
+ * @returns {Array<{id: string, type: string, title: string, state: string, fm: Object}>}
+ */
+function collectNodes(dir, type, state) {
+  const nodes = []
+  let files = []
+  try {
+    files = fs.readdirSync(dir).filter(f => {
+      if (!f.endsWith('.md')) return false
+      try { return !fs.statSync(path.join(dir, f)).isDirectory() } catch (_) { return false }
+    })
+  } catch (_) {
+    return nodes
+  }
+  for (const file of files) {
+    let content = ''
+    try { content = fs.readFileSync(path.join(dir, file), 'utf8') } catch (_) {}
+    const fm = parseFrontmatter(content)
+    const title = extractTitle(content, file)
+    const id = path.join(dir, file)
+    nodes.push({ id, type, title, state, fm })
+  }
+  return nodes
+}
+
+/**
+ * handleChain responde ao GET /api/chain com nodes e edges em JSON.
+ * @param {object} cfg
+ * @param {http.IncomingMessage} req
+ * @param {http.ServerResponse} res
+ */
+function handleChain(cfg, req, res) {
+  const adrDirs = cfg.adrDirs || ['docs/adr']
+  const reqDir = cfg.reqDir || 'docs/req'
+  const roadmapDir = cfg.roadmapDir || 'docs/roadmaps'
+  const namespacing = cfg.roadmapNamespacing || 'flat'
+
+  const allNodes = []
+
+  // ADRs — scan recursivo de subpastas (done/, wip/, etc.)
+  for (const adrDir of adrDirs) {
+    const subfolders = ['done', 'wip', 'backlog', 'blocked', 'abandoned', '']
+    for (const sub of subfolders) {
+      const dir = sub ? path.join(adrDir, sub) : adrDir
+      const nodes = collectNodes(dir, 'adr', sub || 'unknown')
+      allNodes.push(...nodes)
+    }
+  }
+
+  // REQs
+  if (namespacing === 'by_agent') {
+    let agents = cfg.agents || []
+    if (!agents.length) {
+      try {
+        agents = fs.readdirSync(reqDir).filter(f => {
+          try { return fs.statSync(path.join(reqDir, f)).isDirectory() } catch (_) { return false }
+        })
+      } catch (_) {}
+    }
+    for (const agent of agents) {
+      for (const state of ROADMAP_STATES) {
+        const dir = path.join(reqDir, agent, state)
+        allNodes.push(...collectNodes(dir, 'req', state))
+      }
+    }
+  } else {
+    allNodes.push(...collectNodes(reqDir, 'req', 'unknown'))
+  }
+
+  // Roadmaps
+  if (namespacing === 'by_agent') {
+    let agents = cfg.agents || []
+    if (!agents.length) {
+      try {
+        agents = fs.readdirSync(roadmapDir).filter(f => {
+          try { return fs.statSync(path.join(roadmapDir, f)).isDirectory() } catch (_) { return false }
+        })
+      } catch (_) {}
+    }
+    for (const agent of agents) {
+      for (const state of ROADMAP_STATES) {
+        const dir = path.join(roadmapDir, agent, state)
+        allNodes.push(...collectNodes(dir, 'roadmap', state))
+      }
+    }
+  } else {
+    for (const state of ROADMAP_STATES) {
+      const dir = path.join(roadmapDir, state)
+      allNodes.push(...collectNodes(dir, 'roadmap', state))
+    }
+  }
+
+  // Deduplicar por id (path)
+  const nodeMap = new Map()
+  for (const n of allNodes) {
+    if (!nodeMap.has(n.id)) nodeMap.set(n.id, n)
+  }
+
+  // Construir índice por título e nome de arquivo para resolver referências
+  const titleIndex = new Map()  // titulo normalizado -> id
+  const fileIndex = new Map()   // basename -> id
+  for (const [id, n] of nodeMap) {
+    const norm = n.title.toLowerCase().trim()
+    if (!titleIndex.has(norm)) titleIndex.set(norm, id)
+    const base = path.basename(id).replace(/\.md$/, '').toLowerCase()
+    if (!fileIndex.has(base)) fileIndex.set(base, id)
+  }
+
+  // Construir edges a partir dos campos de frontmatter
+  const edges = []
+  const edgeSet = new Set()
+
+  function addEdge(from, to) {
+    const key = `${from}→${to}`
+    if (!edgeSet.has(key)) {
+      edgeSet.add(key)
+      edges.push({ from, to })
+    }
+  }
+
+  function resolveRef(val) {
+    if (!val) return null
+    // Tenta pelo nome de arquivo
+    const base = val.replace(/\.md$/, '').toLowerCase().trim()
+    if (fileIndex.has(base)) return fileIndex.get(base)
+    // Tenta pelo título
+    const norm = val.toLowerCase().trim()
+    if (titleIndex.has(norm)) return titleIndex.get(norm)
+    return null
+  }
+
+  // Campos de link padrão
+  const reqFields = (cfg.linkFields && cfg.linkFields.req) || ['REQ:', 'req:']
+  const adrFields = (cfg.linkFields && cfg.linkFields.adr) || ['ADR:', 'adr:']
+  const roadmapFields = (cfg.linkFields && cfg.linkFields.roadmap) || ['Roadmap:', 'roadmap:']
+
+  for (const [id, node] of nodeMap) {
+    const fm = node.fm || {}
+
+    // Checar campos de frontmatter para criar arestas
+    for (const [fmKey, fmVal] of Object.entries(fm)) {
+      const keyLower = fmKey.toLowerCase()
+      if (keyLower === 'req' || reqFields.some(f => f.toLowerCase().replace(':', '') === keyLower)) {
+        const target = resolveRef(fmVal)
+        if (target && target !== id) addEdge(id, target)
+      }
+      if (keyLower === 'adr' || adrFields.some(f => f.toLowerCase().replace(':', '') === keyLower)) {
+        const target = resolveRef(fmVal)
+        if (target && target !== id) addEdge(id, target)
+      }
+      if (keyLower === 'roadmap' || roadmapFields.some(f => f.toLowerCase().replace(':', '') === keyLower)) {
+        const target = resolveRef(fmVal)
+        if (target && target !== id) addEdge(id, target)
+      }
+    }
+  }
+
+  // Montar nodes de saída sem o campo fm interno
+  const outputNodes = Array.from(nodeMap.values()).map(n => ({
+    id: n.id,
+    type: n.type,
+    title: n.title,
+    state: n.state,
+  }))
+
+  res.writeHead(200, { 'Content-Type': 'application/json' })
+  res.end(JSON.stringify({ nodes: outputNodes, edges }))
+}
+
+module.exports = { handleChain }