trackfw 2.1.1 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "2.1.1",
+  "version": "2.4.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/baseline.js

@@ -0,0 +1,13 @@
+'use strict'
+const { Command } = require('commander')
+const { validateUnfiltered, saveBaseline } = require('../validator')
+
+const cmd = new Command('baseline')
+cmd.description('Grava snapshot das violations atuais em .trackfw-baseline.json')
+cmd.action(async () => {
+  const { violations, warnings } = await validateUnfiltered()
+  saveBaseline(violations, warnings)
+  console.log(`Baseline gravado: ${violations.length} violations, ${warnings.length} warnings`)
+})
+
+module.exports = cmd

package/src/commands/configure.js

@@ -0,0 +1,106 @@
+'use strict'
+const { Command } = require('commander')
+const readline = require('readline')
+const fs = require('fs')
+const path = require('path')
+
+const DEFAULTS = {
+  adr_dirs: 'docs/adr',
+  req_dir: 'docs/req',
+  roadmap_dir: 'docs/roadmaps',
+  wip_limit: '1',
+  link_req: 'REQ:'
+}
+
+/**
+ * Pergunta ao usuário via readline e retorna a resposta como Promise<string>.
+ * Se o usuário pressionar Enter sem digitar nada, retorna o valor padrão.
+ * @param {readline.Interface} rl
+ * @param {string} question
+ * @param {string} defaultValue
+ * @returns {Promise<string>}
+ */
+function ask(rl, question, defaultValue) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim() || defaultValue)
+    })
+  })
+}
+
+/**
+ * Executa o wizard interativo e grava trackfw.yaml.
+ * Exportada separadamente para facilitar testes.
+ * @param {readline.Interface} [rl] — opcional; se não fornecido, cria um novo
+ * @param {string} [cwd] — diretório de trabalho (padrão: process.cwd())
+ * @returns {Promise<{ fieldsWritten: number, filePath: string }>}
+ */
+async function runConfigure(rl, cwd) {
+  const dir = cwd || process.cwd()
+  const yamlPath = path.join(dir, 'trackfw.yaml')
+  let ownRl = false
+
+  if (!rl) {
+    rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    ownRl = true
+  }
+
+  try {
+    // Verificar se já existe e perguntar se recria
+    if (fs.existsSync(yamlPath)) {
+      const answer = await ask(rl, 'trackfw.yaml já existe. Recriar do zero? (s/N) ', 'N')
+      if (answer.toLowerCase() !== 's') {
+        console.log('Operação cancelada.')
+        return { fieldsWritten: 0, filePath: yamlPath }
+      }
+    }
+
+    // Coletar campos via prompts
+    const adrDirs = await ask(rl, `ADR dirs [${DEFAULTS.adr_dirs}]: `, DEFAULTS.adr_dirs)
+    const reqDir = await ask(rl, `REQ dir [${DEFAULTS.req_dir}]: `, DEFAULTS.req_dir)
+    const roadmapDir = await ask(rl, `Roadmap dir [${DEFAULTS.roadmap_dir}]: `, DEFAULTS.roadmap_dir)
+    const wipLimit = await ask(rl, `WIP limit [${DEFAULTS.wip_limit}]: `, DEFAULTS.wip_limit)
+    const linkReq = await ask(rl, `Marcador de REQ [${DEFAULTS.link_req}]: `, DEFAULTS.link_req)
+
+    // Montar campos customizados (somente diferenças dos defaults)
+    const custom = {}
+    if (adrDirs !== DEFAULTS.adr_dirs) custom.adr_dirs = adrDirs
+    if (reqDir !== DEFAULTS.req_dir) custom.req_dir = reqDir
+    if (roadmapDir !== DEFAULTS.roadmap_dir) custom.roadmap_dir = roadmapDir
+    if (wipLimit !== DEFAULTS.wip_limit) custom.wip_limit = wipLimit
+    if (linkReq !== DEFAULTS.link_req) custom['link_fields.req'] = linkReq
+
+    // Gerar conteúdo do YAML
+    let content = '# trackfw.yaml — gerado por trackfw configure\n'
+    const fieldsWritten = Object.keys(custom).length
+
+    if (fieldsWritten > 0) {
+      for (const [key, value] of Object.entries(custom)) {
+        if (key === 'adr_dirs') {
+          content += `adr_dirs:\n  - ${value}\n`
+        } else if (key === 'link_fields.req') {
+          content += `link_fields:\n  req:\n    - "${value}"\n`
+        } else {
+          content += `${key}: ${value}\n`
+        }
+      }
+    }
+
+    fs.writeFileSync(yamlPath, content, 'utf8')
+    console.log(`trackfw.yaml gravado com ${fieldsWritten} campos customizados`)
+
+    return { fieldsWritten, filePath: yamlPath }
+  } finally {
+    if (ownRl) rl.close()
+  }
+}
+
+const cmd = new Command('configure')
+cmd.description('Wizard interativo para criar/atualizar trackfw.yaml')
+cmd.action(async () => {
+  await runConfigure()
+})
+
+module.exports = cmd
+module.exports.runConfigure = runConfigure
+module.exports.DEFAULTS = DEFAULTS

package/src/commands/help.js

@@ -0,0 +1,226 @@
+'use strict'
+const { Command } = require('commander')
+
+const configDocs = {
+  adr_dirs: {
+    type: 'list of strings',
+    default: '["docs/adr"]',
+    description: 'Diretórios onde os ADRs são armazenados.',
+    example: 'adr_dirs:\n  - docs/adr\n  - docs/adr/zeus',
+    impact: 'Todos os diretórios listados são varridos na validação de ADRs.'
+  },
+  req_dir: {
+    type: 'string',
+    default: '"docs/req"',
+    description: 'Diretório onde as REQs são armazenadas.',
+    example: 'req_dir: docs/requisicoes',
+    impact: 'Altera onde o trackfw busca e cria arquivos de REQ.'
+  },
+  roadmap_dir: {
+    type: 'string',
+    default: '"docs/roadmaps"',
+    description: 'Diretório raiz dos roadmaps.',
+    example: 'roadmap_dir: docs/roadmaps',
+    impact: 'Subtrees backlog/, wip/, blocked/, done/, abandoned/ são relativos a este diretório.'
+  },
+  roadmap_namespacing: {
+    type: 'flat|by_agent',
+    default: '"flat"',
+    description: 'Estratégia de namespacing dos roadmaps.',
+    example: 'roadmap_namespacing: by_agent',
+    impact: 'Com by_agent, roadmaps ficam em subpastas por agente (ex: wip/apolo/RM-001.md).'
+  },
+  agents: {
+    type: 'list of strings',
+    default: '[]',
+    description: 'Lista de agentes ativos no projeto.',
+    example: 'agents:\n  - apolo\n  - afrodite',
+    impact: 'Agentes listados têm suas subpastas criadas automaticamente em roadmap_dir.'
+  },
+  governance_mode: {
+    type: 'string',
+    default: '""',
+    description: 'Modo de governança (strict, lenient).',
+    example: 'governance_mode: strict',
+    impact: 'strict bloqueia commits/merges com violations; lenient emite apenas avisos.'
+  },
+  lenient_until: {
+    type: 'date (YYYY-MM-DD)',
+    default: '""',
+    description: 'Data até quando o modo lenient está ativo.',
+    example: 'lenient_until: 2026-12-31',
+    impact: 'Após a data, o modo volta automaticamente para strict.'
+  },
+  wip_limit: {
+    type: 'integer',
+    default: '1',
+    description: 'Limite de itens WIP simultâneos.',
+    example: 'wip_limit: 3',
+    impact: 'Aumentar reduz a frequência de bloqueio.'
+  },
+  wip_by_squad: {
+    type: 'boolean',
+    default: 'false',
+    description: 'Aplicar limite WIP por squad individualmente.',
+    example: 'wip_by_squad: true',
+    impact: 'Cada squad tem seu próprio contador de WIP em vez de um limite global.'
+  },
+  require_req_in_commit: {
+    type: 'boolean',
+    default: 'false',
+    description: 'Exigir referência de REQ em mensagens de commit.',
+    example: 'require_req_in_commit: true',
+    impact: 'Commits sem menção a uma REQ são rejeitados pelo hook de pre-commit.'
+  },
+  'link_fields.req': {
+    type: 'list of strings',
+    default: '["REQ:"]',
+    description: 'Marcadores que identificam link a REQ.',
+    example: 'link_fields:\n  req:\n    - "REQ:"\n    - "Requisito:"',
+    impact: 'Qualquer marcador listado é aceito para detectar vínculo com REQ.'
+  },
+  'link_fields.adr': {
+    type: 'list of strings',
+    default: '["ADR:"]',
+    description: 'Marcadores que identificam link a ADR.',
+    example: 'link_fields:\n  adr:\n    - "ADR:"\n    - "Decision:"',
+    impact: 'Qualquer marcador listado é aceito para detectar vínculo com ADR.'
+  },
+  'link_fields.roadmap': {
+    type: 'list of strings',
+    default: '["Roadmap:"]',
+    description: 'Marcadores que identificam link a Roadmap.',
+    example: 'link_fields:\n  roadmap:\n    - "Roadmap:"',
+    impact: 'Qualquer marcador listado é aceito para detectar vínculo com Roadmap.'
+  },
+  acceptance_markers: {
+    type: 'list of strings',
+    default: '["## Acceptance Criteria", "## Critérios de Aceite"]',
+    description: 'Marcadores de critério de aceite.',
+    example: 'acceptance_markers:\n  - "## Acceptance Criteria"\n  - "## AC"',
+    impact: 'Roadmaps WIP sem nenhum desses marcadores disparam a regra wip_acceptance.'
+  },
+  'rules.wip_has_req': {
+    type: 'off|warning|error',
+    default: '"error"',
+    description: 'Severidade: WIP sem REQ linkada.',
+    example: 'rules:\n  wip_has_req: warning',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.wip_acceptance': {
+    type: 'off|warning|error',
+    default: '"error"',
+    description: 'Severidade: WIP sem critérios de aceite.',
+    example: 'rules:\n  wip_acceptance: warning',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.wip_limit': {
+    type: 'off|warning|error',
+    default: '"error"',
+    description: 'Severidade: excesso de itens WIP.',
+    example: 'rules:\n  wip_limit: warning',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.stale_wip': {
+    type: 'off|warning|error',
+    default: '"warning"',
+    description: 'Severidade: WIP sem atualização recente.',
+    example: 'rules:\n  stale_wip: error',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.adr_orphan': {
+    type: 'off|warning|error',
+    default: '"warning"',
+    description: 'Severidade: ADR sem REQ vinculada.',
+    example: 'rules:\n  adr_orphan: error',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.ref_targets_exist': {
+    type: 'off|warning|error',
+    default: '"warning"',
+    description: 'Severidade: referências com destino inexistente.',
+    example: 'rules:\n  ref_targets_exist: error',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.folder_status': {
+    type: 'off|warning|error',
+    default: '"warning"',
+    description: 'Severidade: coerência entre pasta e status do arquivo.',
+    example: 'rules:\n  folder_status: error',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.filename_uniqueness': {
+    type: 'off|warning|error',
+    default: '"error"',
+    description: 'Severidade: nomes de arquivo duplicados.',
+    example: 'rules:\n  filename_uniqueness: warning',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  },
+  'rules.blocked_by_draft_adr': {
+    type: 'off|warning|error',
+    default: '"error"',
+    description: 'Severidade: REQ bloqueada por ADR em rascunho.',
+    example: 'rules:\n  blocked_by_draft_adr: warning',
+    impact: 'error bloqueia; warning apenas reporta; off desativa a regra.'
+  }
+}
+
+/**
+ * Retorna string com a listagem tabular de todas as keys configuráveis.
+ * @returns {string}
+ */
+function listKeys() {
+  const COL_KEY = 28
+  const COL_DEFAULT = 36
+  const header = 'KEY'.padEnd(COL_KEY) + 'DEFAULT'.padEnd(COL_DEFAULT) + 'DESCRIÇÃO'
+  const sep = '─'.repeat(COL_KEY + COL_DEFAULT + 40)
+  const lines = [header, sep]
+  for (const [key, doc] of Object.entries(configDocs)) {
+    lines.push(
+      key.padEnd(COL_KEY) +
+      doc.default.padEnd(COL_DEFAULT) +
+      doc.description
+    )
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Retorna string com a documentação detalhada de uma key.
+ * Retorna null se a key não existir.
+ * @param {string} key
+ * @returns {string|null}
+ */
+function describeKey(key) {
+  const doc = configDocs[key]
+  if (!doc) return null
+  return [
+    key,
+    `  Type:    ${doc.type}`,
+    `  Default: ${doc.default}`,
+    `  Desc:    ${doc.description}`,
+    `  Example:`,
+    ...doc.example.split('\n').map(l => `    ${l}`),
+    `  Impact:  ${doc.impact}`
+  ].join('\n')
+}
+
+const cmd = new Command('help')
+cmd.description('Exibe documentação das keys configuráveis do trackfw.yaml')
+cmd.argument('[key]', 'key específica para detalhar')
+cmd.action((key) => {
+  if (!key) {
+    console.log(listKeys())
+    return
+  }
+  const output = describeKey(key)
+  if (!output) {
+    console.error(`chave desconhecida: ${key}`)
+    process.exit(1)
+  }
+  console.log(output)
+})
+
+module.exports = cmd
+module.exports.listKeys = listKeys
+module.exports.describeKey = describeKey

package/src/commands/index.js

@@ -22,6 +22,9 @@ function createProgram() {
   program.addCommand(require('./metrics'))
   program.addCommand(require('./sync'))
   program.addCommand(require('./context'))
+  program.addCommand(require('./baseline'))
+  program.addCommand(require('./help'))
+  program.addCommand(require('./configure'))
 
   // plugin dispatch — comandos desconhecidos tentam executar plugin
   program.hook('preSubcommand', () => {})

package/src/config/index.js

@@ -15,6 +15,24 @@ function defaults() {
     wipLimit: 1,
     wipBySquad: false,
     requireReqInCommit: false,
+    // NOVOS campos:
+    linkFields: {
+      req:     ['REQ:'],
+      adr:     ['ADR:'],
+      roadmap: ['Roadmap:'],
+    },
+    acceptanceMarkers: ['## Acceptance Criteria', '## Critérios de Aceite'],
+    rules: {
+      wip_has_req:          'error',
+      wip_acceptance:       'error',
+      wip_limit:            'error',
+      stale_wip:            'warning',
+      adr_orphan:           'warning',
+      ref_targets_exist:    'warning',
+      folder_status:        'warning',
+      filename_uniqueness:  'error',
+      blocked_by_draft_adr: 'error',
+    },
   };
 }
 
@@ -36,31 +54,109 @@ function reset() {
 
 function parse(content, cfg) {
   const lines = content.split('\n');
+
+  // estados existentes
   let inAdrDirs = false;
   let inAgents = false;
   let adrDirs = [];
   let agents = [];
 
+  // NOVOS estados
+  let inLinkFields = false;
+  let inLinkFieldsReq = false;
+  let inLinkFieldsAdr = false;
+  let inLinkFieldsRoadmap = false;
+  let linkFieldsReq = [];
+  let linkFieldsAdr = [];
+  let linkFieldsRoadmap = [];
+
+  let inAcceptanceMarkers = false;
+  let acceptanceMarkers = [];
+
+  let inRules = false;
+  let rules = {};
+
+  function flushBlocks() {
+    if (inAdrDirs && adrDirs.length) cfg.adrDirs = adrDirs;
+    if (inAgents && agents.length) cfg.agents = agents;
+    if (inLinkFields) {
+      if (inLinkFieldsReq && linkFieldsReq.length) cfg.linkFields.req = linkFieldsReq;
+      if (inLinkFieldsAdr && linkFieldsAdr.length) cfg.linkFields.adr = linkFieldsAdr;
+      if (inLinkFieldsRoadmap && linkFieldsRoadmap.length) cfg.linkFields.roadmap = linkFieldsRoadmap;
+    }
+    if (inAcceptanceMarkers && acceptanceMarkers.length) cfg.acceptanceMarkers = acceptanceMarkers;
+    if (inRules && Object.keys(rules).length) Object.assign(cfg.rules, rules);
+    // reset
+    inAdrDirs = false; adrDirs = [];
+    inAgents = false; agents = [];
+    inLinkFields = false;
+    inLinkFieldsReq = false; inLinkFieldsAdr = false; inLinkFieldsRoadmap = false;
+    linkFieldsReq = []; linkFieldsAdr = []; linkFieldsRoadmap = [];
+    inAcceptanceMarkers = false; acceptanceMarkers = [];
+    inRules = false; rules = {};
+  }
+
   for (const rawLine of lines) {
     const line = rawLine.trim();
+    if (!line) continue;
+    const hasIndent = rawLine.length > 0 && (rawLine[0] === ' ' || rawLine[0] === '\t');
+
+    if (!hasIndent) {
+      flushBlocks();
+    }
 
-    if (inAdrDirs) {
-      if (line.startsWith('- ')) {
-        adrDirs.push(line.slice(2).trim());
+    if (hasIndent) {
+      if (inAdrDirs) {
+        if (line.startsWith('- ')) adrDirs.push(line.slice(2).trim());
         continue;
       }
-      inAdrDirs = false;
-      if (adrDirs.length) cfg.adrDirs = adrDirs;
-    }
-    if (inAgents) {
-      if (line.startsWith('- ')) {
-        agents.push(line.slice(2).trim());
+      if (inAgents) {
+        if (line.startsWith('- ')) agents.push(line.slice(2).trim());
+        continue;
+      }
+      if (inAcceptanceMarkers) {
+        if (line.startsWith('- ')) {
+          let val = line.slice(2).trim();
+          val = val.replace(/^["']|["']$/g, '');
+          acceptanceMarkers.push(val);
+        }
+        continue;
+      }
+      if (inRules) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx > 0) {
+          const k = line.slice(0, colonIdx).trim();
+          const v = line.slice(colonIdx + 1).trim();
+          if (k) rules[k] = v;
+        }
+        continue;
+      }
+      if (inLinkFields) {
+        if (line.startsWith('- ')) {
+          let val = line.slice(2).trim();
+          val = val.replace(/^["']|["']$/g, '');
+          if (inLinkFieldsReq) linkFieldsReq.push(val);
+          else if (inLinkFieldsAdr) linkFieldsAdr.push(val);
+          else if (inLinkFieldsRoadmap) linkFieldsRoadmap.push(val);
+        } else {
+          // sub-chave dentro de link_fields
+          const colonIdx = line.indexOf(':');
+          const subKey = colonIdx > 0 ? line.slice(0, colonIdx).trim() : line.replace(':', '').trim();
+          // flush sub-campo anterior
+          if (inLinkFieldsReq && linkFieldsReq.length) { cfg.linkFields.req = linkFieldsReq; linkFieldsReq = []; }
+          if (inLinkFieldsAdr && linkFieldsAdr.length) { cfg.linkFields.adr = linkFieldsAdr; linkFieldsAdr = []; }
+          if (inLinkFieldsRoadmap && linkFieldsRoadmap.length) { cfg.linkFields.roadmap = linkFieldsRoadmap; linkFieldsRoadmap = []; }
+          inLinkFieldsReq = false; inLinkFieldsAdr = false; inLinkFieldsRoadmap = false;
+          if (subKey === 'req') inLinkFieldsReq = true;
+          else if (subKey === 'adr') inLinkFieldsAdr = true;
+          else if (subKey === 'roadmap') inLinkFieldsRoadmap = true;
+        }
         continue;
       }
-      inAgents = false;
-      if (agents.length) cfg.agents = agents;
+      continue;
     }
 
+    // linha top-level
     const colonIdx = line.indexOf(':');
     if (colonIdx < 0) continue;
     const key = line.slice(0, colonIdx).trim();
@@ -68,25 +164,27 @@ function parse(content, cfg) {
     if (!key) continue;
 
     switch (key) {
-      case 'adr_dirs': inAdrDirs = true; adrDirs = []; break;
-      case 'req_dir': cfg.reqDir = val; break;
-      case 'roadmap_dir': cfg.roadmapDir = val; break;
-      case 'roadmap_namespacing': cfg.roadmapNamespacing = val; break;
-      case 'agents': inAgents = true; agents = []; break;
-      case 'governance_mode': cfg.governanceMode = val; break;
-      case 'lenient_until': cfg.lenientUntil = val; break;
-      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 'adr_dirs':              inAdrDirs = true; adrDirs = []; break;
+      case 'req_dir':               cfg.reqDir = val; break;
+      case 'roadmap_dir':           cfg.roadmapDir = val; break;
+      case 'roadmap_namespacing':   cfg.roadmapNamespacing = val; break;
+      case 'agents':                inAgents = true; agents = []; break;
+      case 'governance_mode':       cfg.governanceMode = val; break;
+      case 'lenient_until':         cfg.lenientUntil = val; break;
+      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 'link_fields':           inLinkFields = true; break;
+      case 'acceptance_markers':    inAcceptanceMarkers = true; acceptanceMarkers = []; break;
+      case 'rules':                 inRules = true; rules = {}; break;
     }
   }
 
-  // flush pending lists at EOF
-  if (inAdrDirs && adrDirs.length) cfg.adrDirs = adrDirs;
-  if (inAgents && agents.length) cfg.agents = agents;
+  // flush final (EOF)
+  flushBlocks();
 }
 
-const NAMESPACING_FLAT = 'flat'
-const NAMESPACING_BY_AGENT = 'by_agent'
+const NAMESPACING_FLAT = 'flat';
+const NAMESPACING_BY_AGENT = 'by_agent';
 
 module.exports = { load, reset, defaults, NAMESPACING_FLAT, NAMESPACING_BY_AGENT };

package/src/validator/index.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs')
 const path = require('path')
+const { execSync } = require('child_process')
 const config = require('../config')
 
 const STALE_WIP_DAYS = 7
@@ -22,6 +23,64 @@ function listDir(dir) {
   }
 }
 
+// walkDirMd retorna basenames de todos .md recursivamente dentro de dir.
+function walkDirMd(dir) {
+  const results = []
+  function walk(d) {
+    let entries
+    try { entries = fs.readdirSync(d) } catch (_) { return }
+    for (const name of entries) {
+      const full = path.join(d, name)
+      try {
+        if (fs.statSync(full).isDirectory()) { walk(full) }
+        else if (name.endsWith('.md')) { results.push(name) }
+      } catch (_) {}
+    }
+  }
+  walk(dir)
+  return results
+}
+
+// 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) {
+    function search(d) {
+      let entries
+      try { entries = fs.readdirSync(d) } catch (_) { return null }
+      for (const name of entries) {
+        const full = path.join(d, name)
+        try {
+          if (fs.statSync(full).isDirectory()) {
+            const r = search(full)
+            if (r) return r
+          } else if (name === basename) {
+            return full
+          }
+        } catch (_) {}
+      }
+      return null
+    }
+    const found = search(adrDir)
+    if (found) return found
+  }
+  return null
+}
+
+// gitLastModifiedTime retorna o timestamp (ms) do último commit que tocou o arquivo via git log.
+// Retorna null em caso de erro ou se não houver commits.
+function gitLastModifiedTime(filePath) {
+  try {
+    const out = execSync(`git log -1 --format=%ct -- "${filePath}"`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim()
+    if (out) return parseInt(out, 10) * 1000  // converter para ms
+  } catch (_) {}
+  return null
+}
+
 // resolveWIPDirs retorna todos os diretórios wip/ conforme o modo de namespacing.
 function resolveWIPDirs(cfg) {
   if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
@@ -68,23 +127,26 @@ function parseBlockedADRs(filePath) {
   return adrs
 }
 
-// adrIsDraft verifica se <adrBasename> contém "Status: Draft" em alguma das adrDirs configuradas.
-function adrIsDraft(basename) {
-  const cfg = config.load()
-  for (const adrDir of cfg.adrDirs) {
-    const p = path.join(adrDir, basename)
-    if (fs.existsSync(p)) {
-      try {
-        return fs.readFileSync(p, 'utf8').includes('Status: Draft')
-      } catch (_) {
-        // ignorar erro de leitura
-      }
+// contentHasMarker retorna true se o conteúdo contém algum dos markers sem espaço em branco após.
+function contentHasMarker(content, markers) {
+  for (const marker of markers) {
+    if (content.includes(marker) && !content.includes(marker + ' \n')) {
+      return true
     }
   }
   return false
 }
 
-// validateWIPHasREQ — roadmaps em wip/ sem "REQ:" no conteúdo → violation
+// adrIsDraft verifica se <adrBasename> contém "Status: Draft" buscando recursivamente nas adrDirs.
+function adrIsDraft(basename) {
+  const p = findAdrFile(basename)
+  if (!p) return false
+  try {
+    return fs.readFileSync(p, 'utf8').includes('Status: Draft')
+  } catch (_) { return false }
+}
+
+// validateWIPHasREQ — roadmaps em wip/ sem marker REQ no conteúdo → violation
 // Suporta modo by_agent via resolveWIPDirs.
 function validateWIPHasREQ() {
   const cfg = config.load()
@@ -95,7 +157,7 @@ function validateWIPHasREQ() {
     for (const name of entries) {
       try {
         const content = fs.readFileSync(path.join(wipDir, name), 'utf8')
-        if (!content.includes('REQ:') || content.includes('REQ: \n')) {
+        if (!contentHasMarker(content, cfg.linkFields.req)) {
           violations.push(`roadmap "${name}" is in wip but has no linked REQ`)
         }
       } catch (_) {
@@ -106,7 +168,7 @@ function validateWIPHasREQ() {
   return violations
 }
 
-// validateREQsHaveADR — REQs em <reqDir>/ sem "ADR:" no conteúdo → violation
+// validateREQsHaveADR — REQs em <reqDir>/ sem marker ADR no conteúdo → violation
 function validateREQsHaveADR() {
   const cfg = config.load()
   const entries = listDir(cfg.reqDir)
@@ -114,7 +176,7 @@ function validateREQsHaveADR() {
   for (const name of entries) {
     try {
       const content = fs.readFileSync(path.join(cfg.reqDir, name), 'utf8')
-      if (!content.includes('ADR:') || content.includes('ADR: \n')) {
+      if (!contentHasMarker(content, cfg.linkFields.adr)) {
         violations.push(`req "${name}" has no linked ADR`)
       }
     } catch (_) {
@@ -124,7 +186,7 @@ function validateREQsHaveADR() {
   return violations
 }
 
-// validateBlockedHasREQ — roadmaps em <roadmapDir>/blocked/ sem "REQ:" → violation
+// validateBlockedHasREQ — roadmaps em <roadmapDir>/blocked/ sem marker REQ → violation
 function validateBlockedHasREQ() {
   const cfg = config.load()
   const entries = listDir(cfg.roadmapDir + '/blocked')
@@ -132,7 +194,7 @@ function validateBlockedHasREQ() {
   for (const name of entries) {
     try {
       const content = fs.readFileSync(path.join(cfg.roadmapDir + '/blocked', name), 'utf8')
-      if (!content.includes('REQ:') || content.includes('REQ: \n')) {
+      if (!contentHasMarker(content, cfg.linkFields.req)) {
         violations.push(`roadmap "${name}" is in blocked but has no linked REQ`)
       }
     } catch (_) {
@@ -142,7 +204,7 @@ function validateBlockedHasREQ() {
   return violations
 }
 
-// validateREQsHaveRoadmap — REQs sem "Roadmap:" → violation
+// validateREQsHaveRoadmap — REQs sem marker Roadmap → violation
 function validateREQsHaveRoadmap() {
   const cfg = config.load()
   const entries = listDir(cfg.reqDir)
@@ -150,7 +212,7 @@ function validateREQsHaveRoadmap() {
   for (const name of entries) {
     try {
       const content = fs.readFileSync(path.join(cfg.reqDir, name), 'utf8')
-      if (!content.includes('Roadmap:') || content.includes('Roadmap: \n')) {
+      if (!contentHasMarker(content, cfg.linkFields.roadmap)) {
         violations.push(`req "${name}" has no linked Roadmap`)
       }
     } catch (_) {
@@ -165,7 +227,7 @@ function validateADRsAreReferenced() {
   const cfg = config.load()
   let adrs = []
   for (const adrDir of cfg.adrDirs) {
-    adrs = adrs.concat(listDir(adrDir))
+    adrs = adrs.concat(walkDirMd(adrDir))
   }
 
   const reqEntries = listDir(cfg.reqDir)
@@ -198,11 +260,7 @@ function validateWIPHasAcceptanceCriteria() {
     for (const name of entries) {
       try {
         const content = fs.readFileSync(path.join(wipDir, name), 'utf8')
-        const hasBlock =
-          content.includes('## Acceptance Criteria') ||
-          content.includes('## Critérios de Aceite') ||
-          content.includes('acceptance criteria') ||
-          content.includes('Acceptance Criteria:')
+        const hasBlock = contentHasMarker(content, cfg.acceptanceMarkers)
         if (!hasBlock) {
           violations.push(`roadmap "${name}" is in wip but has no acceptance criteria block`)
         }
@@ -343,10 +401,12 @@ function validateStaleWIP() {
     for (const filePath of files) {
       try {
         const stat = fs.statSync(filePath)
-        const ageMs = now - stat.mtimeMs
+        const gitTime = gitLastModifiedTime(filePath)
+        const ageMs = now - (gitTime !== null ? gitTime : stat.mtimeMs)
         const days = Math.floor(ageMs / (1000 * 60 * 60 * 24))
         if (days >= STALE_WIP_DAYS) {
-          const lastModified = stat.mtime.toISOString().slice(0, 10)
+          const refTime = gitTime !== null ? gitTime : stat.mtimeMs
+          const lastModified = new Date(refTime).toISOString().slice(0, 10)
           const basename = path.basename(filePath)
           warnings.push(
             `roadmap/wip/${basename} has been in WIP for ${days} days (last modified ${lastModified})`
@@ -458,10 +518,11 @@ function validateFrontmatterPresence() {
   const violations = []
 
   for (const adrDir of cfg.adrDirs) {
-    const files = listDir(adrDir).filter(f => f.endsWith('.md'))
-    for (const f of files) {
+    for (const f of walkDirMd(adrDir)) {
+      const fullPath = findAdrFile(f)
+      if (!fullPath) continue
       try {
-        const content = fs.readFileSync(path.join(adrDir, f), 'utf8')
+        const content = fs.readFileSync(fullPath, 'utf8')
         if (!content.startsWith('---')) {
           violations.push(`adr "${f}" has no frontmatter block`)
         }
@@ -483,29 +544,252 @@ function validateFrontmatterPresence() {
   return violations
 }
 
-// validate executa todas as validações e retorna { violations, warnings }
-async function validate() {
+// extractRefPath extrai o valor de um campo (ex: "REQ", "ADR", "Roadmap") que aponta para .md
+function extractRefPath(content, field) {
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    const prefix = field + ':'
+    if (trimmed.startsWith(prefix)) {
+      let val = trimmed.slice(prefix.length).trim()
+      if (!val || val === '—' || val === '-' || val === '–') return null
+      val = val.split(/\s+/)[0]
+      if (val.endsWith('.md')) return val
+    }
+  }
+  return null
+}
+
+// validateRefTargetsExist — verifica se os arquivos referenciados em REQ:, ADR: e Roadmap: existem
+function validateRefTargetsExist() {
+  const cfg = config.load()
+  const warnings = []
+
+  // Roadmaps em wip e blocked: verificar REQ:
+  const dirs = [...resolveWIPDirs(cfg), cfg.roadmapDir + '/blocked']
+  for (const dir of dirs) {
+    for (const name of listDir(dir)) {
+      try {
+        const content = fs.readFileSync(path.join(dir, name), 'utf8')
+        const ref = extractRefPath(content, 'REQ')
+        if (ref && !fs.existsSync(ref)) {
+          warnings.push(`roadmap "${name}" links to REQ "${ref}" which does not exist`)
+        }
+      } catch (_) {}
+    }
+  }
+
+  // REQs: verificar ADR: e Roadmap:
+  for (const name of listDir(cfg.reqDir)) {
+    try {
+      const content = fs.readFileSync(path.join(cfg.reqDir, name), 'utf8')
+      const adrRef = extractRefPath(content, 'ADR')
+      if (adrRef && !fs.existsSync(adrRef)) {
+        warnings.push(`req "${name}" links to ADR "${adrRef}" which does not exist`)
+      }
+      const roadmapRef = extractRefPath(content, 'Roadmap')
+      if (roadmapRef && !fs.existsSync(roadmapRef)) {
+        warnings.push(`req "${name}" links to Roadmap "${roadmapRef}" which does not exist`)
+      }
+    } catch (_) {}
+  }
+
+  return warnings
+}
+
+// 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'],
+  backlog:   ['Backlog', 'backlog'],
+  blocked:   ['Blocked', 'blocked'],
+  done:      ['Done', 'done'],
+  abandoned: ['Abandoned', 'abandoned'],
+}
+
+// validateFolderStatusCoherence — verifica se o status declarado no frontmatter condiz com a pasta
+function validateFolderStatusCoherence() {
+  const cfg = config.load()
+  const warnings = []
+  const states = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
+
+  let dirs = []
+  if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
+    let agents = cfg.agents || []
+    if (agents.length === 0) {
+      try { agents = fs.readdirSync(cfg.roadmapDir).filter(f => {
+        try { return fs.statSync(path.join(cfg.roadmapDir, f)).isDirectory() } catch (_) { return false }
+      }) } catch (_) { agents = [] }
+    }
+    for (const agent of agents) {
+      for (const state of states) {
+        dirs.push({ dir: path.join(cfg.roadmapDir, agent, state), state })
+      }
+    }
+  } else {
+    for (const state of states) {
+      dirs.push({ dir: path.join(cfg.roadmapDir, state), state })
+    }
+  }
+
+  for (const { dir, state } of dirs) {
+    for (const name of listDir(dir).filter(f => f.endsWith('.md'))) {
+      try {
+        const content = fs.readFileSync(path.join(dir, name), 'utf8')
+        // Extrair status do frontmatter
+        let declared = ''
+        if (content.startsWith('---')) {
+          const end = content.indexOf('\n---', 3)
+          if (end > 0) {
+            for (const line of content.slice(3, end).split('\n')) {
+              const t = line.trim()
+              if (t.startsWith('status:')) {
+                declared = t.slice('status:'.length).trim().replace(/['"]/g, '')
+                break
+              }
+            }
+          }
+        }
+        if (!declared) continue
+        const expected = FOLDER_TO_STATUS[state] || []
+        if (!expected.some(e => e.toLowerCase() === declared.toLowerCase())) {
+          warnings.push(`roadmap "${name}": folder is "${state}" but status declares "${declared}"`)
+        }
+      } catch (_) {}
+    }
+  }
+  return warnings
+}
+
+// validateFilenameUniqueness — verifica que o mesmo filename não aparece em múltiplos estados
+function validateFilenameUniqueness() {
+  const cfg = config.load()
+  const states = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
+  const seen = {}  // filename → [states]
+
+  if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
+    let agents = cfg.agents || []
+    if (agents.length === 0) {
+      try { agents = fs.readdirSync(cfg.roadmapDir).filter(f => {
+        try { return fs.statSync(path.join(cfg.roadmapDir, f)).isDirectory() } catch (_) { return false }
+      }) } catch (_) { agents = [] }
+    }
+    for (const agent of agents) {
+      for (const state of states) {
+        for (const name of listDir(path.join(cfg.roadmapDir, agent, state))) {
+          const key = agent + '/' + name
+          if (!seen[key]) seen[key] = []
+          seen[key].push(state)
+        }
+      }
+    }
+  } else {
+    for (const state of states) {
+      for (const name of listDir(path.join(cfg.roadmapDir, state))) {
+        if (!seen[name]) seen[name] = []
+        seen[name].push(state)
+      }
+    }
+  }
+
+  const violations = []
+  for (const [name, stateList] of Object.entries(seen)) {
+    if (stateList.length > 1) {
+      violations.push(`roadmap "${name}" appears in multiple states: [${stateList.join(', ')}]`)
+    }
+  }
+  return violations
+}
+
+// ruleSeverity retorna a severidade configurada para uma regra ('error'|'warning'|'off').
+function ruleSeverity(name) {
+  const cfg = config.load()
+  return cfg.rules[name] || 'error'
+}
+
+// applyRule distribui msgs para violations ou warnings conforme a severidade configurada.
+// Se severidade for 'off', descarta silenciosamente.
+function applyRule(ruleName, msgs, violations, warnings) {
+  if (!msgs || msgs.length === 0) return
+  const severity = ruleSeverity(ruleName)
+  if (severity === 'off') return
+  if (severity === 'warning') {
+    warnings.push(...msgs)
+  } else {
+    violations.push(...msgs)
+  }
+}
+
+const BASELINE_FILE = '.trackfw-baseline.json'
+
+// loadBaseline carrega o baseline do arquivo .trackfw-baseline.json.
+// Retorna null se o arquivo não existir.
+function loadBaseline() {
+  try {
+    const data = fs.readFileSync(BASELINE_FILE, 'utf8')
+    return JSON.parse(data)
+  } catch (e) {
+    if (e.code === 'ENOENT') return null
+    throw new Error(`Erro ao ler baseline: ${e.message}`)
+  }
+}
+
+// saveBaseline salva snapshot de violations e warnings em .trackfw-baseline.json.
+function saveBaseline(violations, warnings) {
+  const bf = {
+    created: new Date().toISOString(),
+    violations,
+    warnings,
+  }
+  fs.writeFileSync(BASELINE_FILE, JSON.stringify(bf, null, 2), 'utf8')
+}
+
+// validateUnfiltered executa todas as validações e retorna { violations, warnings } sem ratchet.
+async function validateUnfiltered() {
   const wipLimitResult = validateWIPLimit()
-  let violations = [
-    ...validateWIPHasREQ(),
-    ...validateREQsHaveADR(),
-    ...validateBlockedHasREQ(),
-    ...validateREQsHaveRoadmap(),
-    ...validateADRsAreReferenced(),
-    ...validateWIPHasAcceptanceCriteria(),
-    ...validateREQsNotBlockedByDraftADRs(),
-    ...validateFrontmatterPresence(),
-    ...wipLimitResult.violations,
-  ]
-  let warnings = [
-    ...wipLimitResult.warnings,
-    ...validateStaleWIP(),
-  ]
+  const violations = []
+  const warnings = []
+
+  // Regras com severidade configurável via applyRule
+  applyRule('wip_has_req',          validateWIPHasREQ(),                   violations, warnings)
+  applyRule('wip_acceptance',       validateWIPHasAcceptanceCriteria(),    violations, warnings)
+  applyRule('wip_limit',            wipLimitResult.violations,             violations, warnings)
+  applyRule('adr_orphan',           validateADRsAreReferenced(),           violations, warnings)
+  applyRule('stale_wip',            validateStaleWIP(),                    violations, warnings)
+  applyRule('ref_targets_exist',    validateRefTargetsExist(),             violations, warnings)
+  applyRule('folder_status',        validateFolderStatusCoherence(),       violations, warnings)
+  applyRule('filename_uniqueness',  validateFilenameUniqueness(),          violations, warnings)
+  applyRule('blocked_by_draft_adr', validateREQsNotBlockedByDraftADRs(),  violations, warnings)
+
+  // Regras diretas (sem configuração de severidade): violations sempre
+  violations.push(...validateREQsHaveADR())
+  violations.push(...validateBlockedHasREQ())
+  violations.push(...validateREQsHaveRoadmap())
+  violations.push(...validateFrontmatterPresence())
+
+  // warnings diretos do WIP limit (não configuráveis)
+  warnings.push(...wipLimitResult.warnings)
+
+  return { violations, warnings }
+}
+
+// validate executa todas as validações, aplica ratchet (baseline) e modo lenient.
+// Retorna { violations, warnings }.
+async function validate() {
+  const result = await validateUnfiltered()
+  let { violations, warnings } = result
+
+  // Ratchet: filtrar violations que já estavam no baseline
+  const baseline = loadBaseline()
+  if (baseline) {
+    const baselineSet = new Set(baseline.violations || [])
+    violations = violations.filter(v => !baselineSet.has(v))
+  }
+
   // Modo lenient: mover violations para warnings, exit code 0
   if (isLenient()) {
     warnings = [...warnings, ...violations]
     violations = []
   }
+
   return { violations, warnings }
 }
 
@@ -587,6 +871,9 @@ async function getStatus() {
 
 module.exports = {
   validate,
+  validateUnfiltered,
+  loadBaseline,
+  saveBaseline,
   getStatus,
   isLenient,
   lenientUntilDate,
@@ -609,4 +896,16 @@ module.exports = {
   readWIPConfig,
   parseSquadFromFrontmatter,
   validateFrontmatterPresence,
+  // novas funções ML-1B
+  walkDirMd,
+  findAdrFile,
+  gitLastModifiedTime,
+  extractRefPath,
+  validateRefTargetsExist,
+  validateFolderStatusCoherence,
+  validateFilenameUniqueness,
+  // novas funções ML-2B
+  contentHasMarker,
+  ruleSeverity,
+  applyRule,
 }