trackfw 1.1.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Governed software delivery framework: ADR → REQ → ROADMAP → kanban",
   "keywords": [
     "cli",

package/src/commands/adr.js

@@ -25,7 +25,7 @@ cmd.command('new <title>')
 cmd.command('list')
   .description(t('adr.list.description'))
   .action(async () => {
-    await generators.listADRs('docs/adr')
+    await generators.listADRs(require('../config').load().adrDirs[0])
   })
 
 module.exports = cmd

package/src/commands/discover.js

@@ -0,0 +1,359 @@
+'use strict';
+
+const { Command } = require('commander');
+const fs = require('fs');
+const path = require('path');
+
+function scan(rootDir) {
+  const r = {
+    adrDirs: [],
+    reqDir: '',
+    roadmapDir: '',
+    roadmapNamespacing: 'flat',
+    agents: [],
+    adrCount: 0,
+    reqCount: 0,
+    roadmapCount: 0,
+    hasTrackfwYAML: false,
+    hasTrackfwLog: false,
+    governanceScore: 0,
+    hookFramework: 'none',
+    ciSystem: 'none',
+  };
+
+  // trackfw.yaml
+  r.hasTrackfwYAML = fs.existsSync(path.join(rootDir, 'trackfw.yaml'));
+
+  // REQ dir
+  for (const candidate of ['docs/req', 'docs/requisições', 'docs/requirements', 'docs/reqs']) {
+    const full = path.join(rootDir, candidate);
+    if (isDir(full)) {
+      r.reqDir = candidate;
+      r.reqCount = countMD(full);
+      break;
+    }
+  }
+
+  // ADR dirs
+  const adrRoot = path.join(rootDir, 'docs', 'adr');
+  if (isDir(adrRoot)) {
+    const subDirs = listSubDirs(adrRoot);
+    if (subDirs.length > 0) {
+      for (const sub of subDirs) {
+        const rel = 'docs/adr/' + sub;
+        r.adrDirs.push(rel);
+        r.adrCount += countMD(path.join(rootDir, rel));
+      }
+    } else {
+      r.adrDirs = ['docs/adr'];
+      r.adrCount = countMD(adrRoot);
+    }
+  }
+
+  // Roadmap dir e namespacing
+  const roadmapRoot = path.join(rootDir, 'docs', 'roadmaps');
+  if (isDir(roadmapRoot)) {
+    r.roadmapDir = 'docs/roadmaps';
+    const agentDirs = listSubDirs(roadmapRoot);
+    let byAgent = false;
+    const agents = [];
+    for (const sub of agentDirs) {
+      const wipDir = path.join(roadmapRoot, sub, 'wip');
+      const backlogDir = path.join(roadmapRoot, sub, 'backlog');
+      const doneDir = path.join(roadmapRoot, sub, 'done');
+      const abandonedDir = path.join(roadmapRoot, sub, 'abandoned');
+      const blockedDir = path.join(roadmapRoot, sub, 'blocked');
+      if (isDir(wipDir) || isDir(backlogDir) || isDir(doneDir) || isDir(abandonedDir) || isDir(blockedDir)) {
+        byAgent = true;
+        agents.push(sub);
+      }
+    }
+    if (byAgent) {
+      r.roadmapNamespacing = 'by_agent';
+      r.agents = agents;
+      for (const agent of agents) {
+        for (const state of ['backlog', 'wip', 'blocked', 'done', 'abandoned']) {
+          r.roadmapCount += countMD(path.join(roadmapRoot, agent, state));
+        }
+      }
+    } else {
+      r.roadmapNamespacing = 'flat';
+      for (const state of ['backlog', 'wip', 'blocked', 'done', 'abandoned']) {
+        r.roadmapCount += countMD(path.join(roadmapRoot, state));
+      }
+    }
+
+    r.hasTrackfwLog = fs.existsSync(path.join(roadmapRoot, '.trackfw-log'));
+  }
+
+  // Hook framework
+  if (isFile(path.join(rootDir, 'lefthook.yml')) || isFile(path.join(rootDir, '.lefthook.yml'))) {
+    r.hookFramework = 'lefthook';
+  } else if (isDir(path.join(rootDir, '.husky'))) {
+    r.hookFramework = 'husky';
+  } else if (isFile(path.join(rootDir, '.pre-commit-config.yaml'))) {
+    r.hookFramework = 'pre-commit';
+  } else {
+    r.hookFramework = 'none';
+  }
+
+  // CI
+  if (isDir(path.join(rootDir, '.github', 'workflows'))) {
+    r.ciSystem = 'github-actions';
+  } else if (isFile(path.join(rootDir, '.gitlab-ci.yml'))) {
+    r.ciSystem = 'gitlab';
+  } else {
+    r.ciSystem = 'none';
+  }
+
+  r.governanceScore = calcScore(r);
+  return r;
+}
+
+function calcScore(r) {
+  let score = 0;
+  if (r.adrCount > 0) score += 20;
+  if (r.reqCount > 0) score += 20;
+  if (r.roadmapCount > 0) score += 20;
+  if (r.hasTrackfwYAML) score += 20;
+  if (r.hasTrackfwLog) score += 20;
+  return score;
+}
+
+function generateYAML(r) {
+  let out = '# trackfw configuration — gerado por trackfw discover\n';
+  out += '# governance_mode: lenient permite validação não-bloqueante durante onboarding\n\n';
+  out += 'governance_mode: lenient\n\n';
+
+  if (r.adrDirs.length > 0) {
+    out += 'adr_dirs:\n';
+    r.adrDirs.forEach(d => { out += `  - ${d}\n`; });
+  } else {
+    out += 'adr_dirs:\n  - docs/adr\n';
+  }
+
+  out += `req_dir: ${r.reqDir || 'docs/req'}\n`;
+  out += `roadmap_dir: ${r.roadmapDir || 'docs/roadmaps'}\n`;
+  out += `roadmap_namespacing: ${r.roadmapNamespacing}\n`;
+
+  if (r.agents.length > 0) {
+    out += 'agents:\n';
+    r.agents.forEach(a => { out += `  - ${a}\n`; });
+  }
+
+  out += `hooks: ${r.hookFramework}\n`;
+  out += `ci: ${r.ciSystem}\n`;
+
+  return out;
+}
+
+function generateBootstrapLog(r, rootDir) {
+  let out = '';
+  const roadmapRoot = path.join(rootDir, r.roadmapDir);
+
+  const appendEntries = (dir, agent) => {
+    if (!isDir(dir)) return;
+    for (const entry of fs.readdirSync(dir)) {
+      if (!entry.endsWith('.md')) continue;
+      const filePath = path.join(dir, entry);
+      const stat = fs.statSync(filePath);
+      const ts = stat.mtime.toISOString().slice(0, 16).replace('T', ' ');
+      const basename = agent ? agent + '/' + entry : entry;
+      out += `${ts}  ${basename.padEnd(50)}  backlog → done\n`;
+    }
+  };
+
+  if (r.roadmapNamespacing === 'by_agent') {
+    for (const agent of r.agents) {
+      appendEntries(path.join(roadmapRoot, agent, 'done'), agent);
+    }
+  } else {
+    appendEntries(path.join(roadmapRoot, 'done'), '');
+  }
+
+  return out;
+}
+
+// installGates instala artefatos de governança: validate script, hook entry, CI workflow.
+function installGates(r, rootDir) {
+  writeValidateScript(rootDir);
+  installHook(r.hookFramework, rootDir);
+  if (r.ciSystem === 'github-actions') {
+    writeCIWorkflow(rootDir);
+  }
+}
+
+function writeValidateScript(rootDir) {
+  const scriptsDir = path.join(rootDir, 'scripts');
+  if (!isDir(scriptsDir)) fs.mkdirSync(scriptsDir, { recursive: true });
+  const content = '#!/usr/bin/env bash\nset -euo pipefail\ntrackfw validate\n';
+  const dest = path.join(scriptsDir, 'trackfw-validate.sh');
+  fs.writeFileSync(dest, content, { mode: 0o755 });
+}
+
+function installHook(framework, rootDir) {
+  const hookEntry = '\npre-commit:\n  commands:\n    trackfw-validate:\n      run: scripts/trackfw-validate.sh\n';
+  const huskyEntry = '\nscripts/trackfw-validate.sh\n';
+
+  if (framework === 'lefthook') {
+    let cfgPath = path.join(rootDir, 'lefthook.yml');
+    if (!isFile(cfgPath)) cfgPath = path.join(rootDir, '.lefthook.yml');
+    const content = fs.readFileSync(cfgPath, 'utf8');
+    if (content.includes('trackfw')) return; // idempotente
+    fs.appendFileSync(cfgPath, hookEntry, 'utf8');
+  } else if (framework === 'husky') {
+    const huskyHook = path.join(rootDir, '.husky', 'pre-commit');
+    fs.appendFileSync(huskyHook, huskyEntry, 'utf8');
+  } else {
+    console.log('⚠ No hook framework detected — skipping hook installation');
+  }
+}
+
+function writeCIWorkflow(rootDir) {
+  const workflowsDir = path.join(rootDir, '.github', 'workflows');
+  if (!isDir(workflowsDir)) fs.mkdirSync(workflowsDir, { recursive: true });
+  const dest = path.join(workflowsDir, 'trackfw-validate.yml');
+  if (isFile(dest)) return; // idempotente
+  const content = `name: trackfw validate
+on: [push, pull_request]
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+      - run: go install github.com/kgsaran/trackfw/cmd/trackfw@latest
+      - run: trackfw validate
+`;
+  fs.writeFileSync(dest, content, 'utf8');
+}
+
+// helpers
+function isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+function countMD(dir) {
+  let n = 0;
+  function walk(d) {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isDirectory()) walk(path.join(d, e.name));
+      else if (e.name.endsWith('.md')) n++;
+    }
+  }
+  walk(dir);
+  return n;
+}
+
+function listSubDirs(dir) {
+  try {
+    return fs.readdirSync(dir).filter(f => {
+      try { return fs.statSync(path.join(dir, f)).isDirectory(); } catch { return false; }
+    });
+  } catch { return []; }
+}
+
+const cmd = new Command('discover');
+cmd.description('Scan the repository and auto-detect the governance structure');
+cmd.option('--init', 'generate trackfw.yaml calibrated for this project');
+cmd.option('--bootstrap-log', 'create retroactive .trackfw-log from done/ files');
+cmd.action((opts) => {
+  const cwd = process.cwd();
+  console.log(`trackfw discover — scanning ${cwd}\n`);
+
+  const r = scan(cwd);
+
+  // ADR dirs
+  if (r.adrCount > 0) {
+    const dirs = r.adrDirs.join(', ');
+    console.log(`✓ ADRs found:      ${String(r.adrCount).padEnd(4)}  (${dirs})`);
+  } else {
+    console.log('⚠ No ADRs found');
+  }
+
+  // REQ dir
+  if (r.reqCount > 0) {
+    console.log(`✓ REQs found:      ${String(r.reqCount).padEnd(4)}  (${r.reqDir})`);
+  } else {
+    console.log('⚠ No REQs found');
+  }
+
+  // Roadmaps
+  if (r.roadmapCount > 0) {
+    const mode = r.roadmapNamespacing === 'by_agent' ? 'by_agent mode' : r.roadmapNamespacing;
+    console.log(`✓ Roadmaps found:  ${String(r.roadmapCount).padEnd(4)}  (${r.roadmapDir} — ${mode})`);
+  } else {
+    console.log('⚠ No roadmaps found');
+  }
+
+  // Agents
+  if (r.agents.length > 0) {
+    console.log(`✓ Agents detected: ${r.agents.join(', ')}`);
+  }
+
+  // trackfw.yaml
+  if (!r.hasTrackfwYAML) {
+    console.log('⚠ No trackfw.yaml — run with --init to generate one');
+  } else {
+    console.log('✓ trackfw.yaml found');
+  }
+
+  // .trackfw-log
+  if (!r.hasTrackfwLog) {
+    console.log('⚠ No .trackfw-log — run with --bootstrap-log to create retroactive history');
+  } else {
+    console.log('✓ .trackfw-log found');
+  }
+
+  // hooks
+  if (r.hookFramework !== 'none') {
+    console.log(`✓ Hooks: ${r.hookFramework}`);
+  } else {
+    console.log('⚠ No hook framework detected');
+  }
+
+  // CI
+  if (r.ciSystem !== 'none') {
+    console.log(`✓ CI: ${r.ciSystem}`);
+  } else {
+    console.log('⚠ No CI system detected');
+  }
+
+  console.log(`\nGovernance Score: ${r.governanceScore}/100`);
+
+  if (opts.init) {
+    const yaml = generateYAML(r);
+    fs.writeFileSync('trackfw.yaml', yaml, 'utf8');
+    console.log('\n✓ trackfw.yaml generated');
+    try {
+      installGates(r, cwd);
+      console.log('✓ governance gates installed');
+    } catch (e) {
+      console.log(`⚠ gates install partial: ${e.message}`);
+    }
+  }
+
+  if (opts.bootstrapLog) {
+    if (!r.roadmapDir) {
+      console.error('⚠ No roadmap dir detected — cannot bootstrap log');
+      return;
+    }
+    const logContent = generateBootstrapLog(r, cwd);
+    const logPath = r.roadmapDir + '/.trackfw-log';
+    fs.appendFileSync(logPath, logContent, 'utf8');
+    console.log(`✓ bootstrap log written to ${logPath}`);
+  }
+});
+
+module.exports = cmd;
+module.exports.scan = scan;
+module.exports.generateYAML = generateYAML;
+module.exports.generateBootstrapLog = generateBootstrapLog;

package/src/commands/index.js

@@ -18,6 +18,7 @@ function createProgram() {
   program.addCommand(require('./status'))
   program.addCommand(require('./log'))
   program.addCommand(require('./plugins'))
+  program.addCommand(require('./discover'))
 
   // plugin dispatch — comandos desconhecidos tentam executar plugin
   program.hook('preSubcommand', () => {})

package/src/commands/req.js

@@ -64,7 +64,7 @@ cmd.command('new <title>')
 cmd.command('list')
   .description(t('req.list.description'))
   .action(async () => {
-    listREQs('docs/req')
+    listREQs(require('../config').load().reqDir)
   })
 
 module.exports = cmd

package/src/config/index.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function defaults() {
+  return {
+    adrDirs: ['docs/adr'],
+    reqDir: 'docs/req',
+    roadmapDir: 'docs/roadmaps',
+    roadmapNamespacing: 'flat',
+    agents: [],
+    governanceMode: '',
+    lenientUntil: '',
+    wipLimit: 1,
+    wipBySquad: false,
+    requireReqInCommit: false,
+  };
+}
+
+let _instance = null;
+
+function load(cwd) {
+  if (_instance) return _instance;
+  _instance = defaults();
+  const yamlPath = path.join(cwd || process.cwd(), 'trackfw.yaml');
+  if (!fs.existsSync(yamlPath)) return _instance;
+  const content = fs.readFileSync(yamlPath, 'utf8');
+  parse(content, _instance);
+  return _instance;
+}
+
+function reset() {
+  _instance = null;
+}
+
+function parse(content, cfg) {
+  const lines = content.split('\n');
+  let inAdrDirs = false;
+  let inAgents = false;
+  let adrDirs = [];
+  let agents = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    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());
+        continue;
+      }
+      inAgents = false;
+      if (agents.length) cfg.agents = agents;
+    }
+
+    const colonIdx = line.indexOf(':');
+    if (colonIdx < 0) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const val = line.slice(colonIdx + 1).trim();
+    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 'require_req_in_commit': cfg.requireReqInCommit = val === 'true'; break;
+    }
+  }
+
+  // flush pending lists at EOF
+  if (inAdrDirs && adrDirs.length) cfg.adrDirs = adrDirs;
+  if (inAgents && agents.length) cfg.agents = agents;
+}
+
+const NAMESPACING_FLAT = 'flat'
+const NAMESPACING_BY_AGENT = 'by_agent'
+
+module.exports = { load, reset, defaults, NAMESPACING_FLAT, NAMESPACING_BY_AGENT };

package/src/generators/adr.js

@@ -40,11 +40,12 @@ function today() {
  * @returns {Promise<void>}
  */
 async function newADR(content) {
-  fs.mkdirSync('docs/adr', { recursive: true })
+  const adrDir = require('../config').load().adrDirs[0]
+  fs.mkdirSync(adrDir, { recursive: true })
 
   const slug = toSlug(content.title)
   const date = today()
-  const filename = `docs/adr/ADR-${date}-${slug}.md`
+  const filename = `${adrDir}/ADR-${date}-${slug}.md`
 
   const contextSection = content.context || '<!-- What is the situation that motivates this decision? -->'
   const decisionSection = content.decision || '<!-- What was decided? -->'
@@ -129,10 +130,10 @@ function parseADRStatus(filepath) {
  * @returns {Promise<string>} basename do arquivo criado
  */
 async function newADRDraft(slug) {
-  fs.mkdirSync('docs/adr', { recursive: true })
+  const adrDir = require('../config').load().adrDirs[0]
+  fs.mkdirSync(adrDir, { recursive: true })
 
   // Verificar idempotência: buscar arquivo existente com o mesmo slug
-  const adrDir = 'docs/adr'
   const existing = fs.existsSync(adrDir)
     ? fs.readdirSync(adrDir).find((f) => f.match(new RegExp(`^ADR-.*-${slug}\\.md$`)))
     : null
@@ -144,7 +145,7 @@ async function newADRDraft(slug) {
 
   const date = today()
   const filename = `ADR-${date}-${slug}.md`
-  const filepath = path.join('docs/adr', filename)
+  const filepath = path.join(adrDir, filename)
   const title = slugToTitle(slug)
 
   const body = `# ADR: ${title}

package/src/generators/init.js

@@ -48,6 +48,13 @@ backend_framework: ${cfg.backendFramework || ''}
 pkg_manager: ${cfg.pkgManager || ''}
 hooks: ${cfg.hooks || ''}
 ci: ${cfg.ci || ''}
+
+# governance paths (edit to match your project structure)
+adr_dirs:
+  - docs/adr
+req_dir: docs/req
+roadmap_dir: docs/roadmaps
+roadmap_namespacing: flat
 `
   fs.writeFileSync('trackfw.yaml', content, 'utf8')
   console.log('  ✓ trackfw.yaml')

package/src/generators/req.js

@@ -69,11 +69,12 @@ function toSlug(s) {
  * @returns {Promise<void>}
  */
 async function newREQ(content) {
-  fs.mkdirSync('docs/req', { recursive: true })
+  const reqDir = require('../config').load().reqDir
+  fs.mkdirSync(reqDir, { recursive: true })
 
   const slug = toSlug(content.title)
   const date = new Date().toISOString().slice(0, 10)
-  const filename = `docs/req/REQ-${date}-${slug}.md`
+  const filename = `${reqDir}/REQ-${date}-${slug}.md`
 
   const motivationSection = content.motivation || '<!-- Why is this requirement needed? What problem does it solve? -->'
   const criteriaSection = content.criteria || '- [ ]\n- [ ]'

package/src/generators/roadmap.js

@@ -1,40 +1,80 @@
 'use strict'
 const fs = require('fs')
 const path = require('path')
+const config = require('../config')
 
-const VALID_STATES = {
-  backlog:   'docs/roadmaps/backlog',
-  wip:       'docs/roadmaps/wip',
-  blocked:   'docs/roadmaps/blocked',
-  done:      'docs/roadmaps/done',
-  abandoned: 'docs/roadmaps/abandoned',
+const STATE_ORDER = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
+
+// stateDir retorna o caminho do diretório para um estado válido no modo flat, ou null se inválido.
+function stateDir(state) {
+  const cfg = config.load()
+  const valid = ['backlog', 'wip', 'blocked', 'done', 'abandoned']
+  if (!valid.includes(state)) return null
+  return cfg.roadmapDir + '/' + state
 }
 
-const STATE_ORDER = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
+// agentStateDir retorna o diretório para um agente+estado em modo by_agent.
+// agent=null usa o primeiro agente configurado (ou "default" se lista vazia).
+function agentStateDir(agent, state) {
+  const cfg = config.load()
+  const valid = ['backlog', 'wip', 'blocked', 'done', 'abandoned']
+  if (!valid.includes(state)) return null
+  if (!agent) {
+    agent = cfg.agents && cfg.agents.length > 0 ? cfg.agents[0] : 'default'
+  }
+  return cfg.roadmapDir + '/' + agent + '/' + state
+}
 
-const TRANSITION_LOG_PATH = 'docs/roadmaps/.trackfw-log'
+// logPath retorna o caminho do arquivo de log de transições.
+function logPath() {
+  return config.load().roadmapDir + '/.trackfw-log'
+}
 
 /**
- * listRoadmaps — lista roadmaps agrupados por estado (wip, backlog, blocked, done, abandoned).
+ * listRoadmaps — lista roadmaps agrupados por estado (e por agente em modo by_agent).
  * Se nenhum encontrado imprime mensagem orientando o usuário.
  */
 function listRoadmaps() {
+  const cfg = config.load()
   let found = false
 
-  for (const state of STATE_ORDER) {
-    const dir = VALID_STATES[state]
-    let files = []
-    try {
-      files = fs.readdirSync(dir).filter(f => !fs.statSync(path.join(dir, f)).isDirectory() && f.endsWith('.md'))
-    } catch (_) {
-      continue
+  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 = [] }
     }
-    if (files.length === 0) continue
-
-    found = true
-    console.log(`[${state}]`)
-    for (const f of files) {
-      console.log(`  ${f}`)
+    for (const agent of agents) {
+      for (const state of STATE_ORDER) {
+        const dir = cfg.roadmapDir + '/' + agent + '/' + state
+        let files = []
+        try {
+          files = fs.readdirSync(dir).filter(f => {
+            try { return !fs.statSync(path.join(dir, f)).isDirectory() && f.endsWith('.md') } catch (_) { return false }
+          })
+        } catch (_) { continue }
+        if (files.length === 0) continue
+        found = true
+        console.log(`[${agent}/${state}]`)
+        for (const f of files) console.log(`  ${f}`)
+      }
+    }
+  } else {
+    for (const state of STATE_ORDER) {
+      const dir = cfg.roadmapDir + '/' + state
+      let files = []
+      try {
+        files = fs.readdirSync(dir).filter(f => {
+          try { return !fs.statSync(path.join(dir, f)).isDirectory() && f.endsWith('.md') } catch (_) { return false }
+        })
+      } catch (_) { continue }
+      if (files.length === 0) continue
+      found = true
+      console.log(`[${state}]`)
+      for (const f of files) console.log(`  ${f}`)
     }
   }
 
@@ -44,8 +84,8 @@ function listRoadmaps() {
 }
 
 /**
- * showRoadmap — busca docs/roadmaps/ESTADO/NOME*.md (partial match), imprime cabeçalho + conteúdo.
- * 0 matches: erro. múltiplos: lista + erro. 1 match: imprime cabeçalho e conteúdo.
+ * showRoadmap — busca <roadmapDir>/ESTADO/NOME*.md (partial match, flat) ou
+ * <roadmapDir>/AGENTE/ESTADO/NOME*.md (by_agent), imprime cabeçalho + conteúdo.
  */
 function showRoadmap(name) {
   const matches = findRoadmapMatches(name)
@@ -58,9 +98,7 @@ function showRoadmap(name) {
 
   if (matches.length > 1) {
     console.log('Multiple roadmaps found — be more specific:')
-    for (const m of matches) {
-      console.log(`  ${m}`)
-    }
+    for (const m of matches) console.log(`  ${m}`)
     console.error(`ambiguous match for "${name}"`)
     process.exitCode = 1
     return
@@ -78,12 +116,12 @@ function showRoadmap(name) {
 
 /**
  * moveRoadmap — move arquivo para diretório do estado alvo.
- * Valida estado, procura arquivo em qualquer estado (case-insensitive partial match),
- * move com fs.renameSync, chama appendTransitionLog, imprime confirmação.
+ * Em modo by_agent, mantém o agente na hierarquia.
  */
 function moveRoadmap(name, state) {
-  const targetDir = VALID_STATES[state]
-  if (!targetDir) {
+  const cfg = config.load()
+  const valid = ['backlog', 'wip', 'blocked', 'done', 'abandoned']
+  if (!valid.includes(state)) {
     console.error(`invalid state "${state}" — valid states: backlog, wip, blocked, done, abandoned`)
     process.exitCode = 1
     return
@@ -97,9 +135,7 @@ function moveRoadmap(name, state) {
   }
   if (matches.length > 1) {
     console.log('Multiple roadmaps found — be more specific:')
-    for (const m of matches) {
-      console.log(`  ${m}`)
-    }
+    for (const m of matches) console.log(`  ${m}`)
     console.error(`ambiguous match for "${name}"`)
     process.exitCode = 1
     return
@@ -107,22 +143,41 @@ function moveRoadmap(name, state) {
 
   const src = matches[0]
   const basename = path.basename(src)
-  const fromState = path.basename(path.dirname(src))
+  let targetDir, fromState, logBasename
+
+  if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
+    const agentDir = path.dirname(path.dirname(src))
+    const agent = path.basename(agentDir)
+    fromState = path.basename(path.dirname(src))
+    targetDir = agentStateDir(agent, state)
+    if (!targetDir) {
+      console.error(`invalid state "${state}"`)
+      process.exitCode = 1
+      return
+    }
+    logBasename = agent + '/' + basename
+  } else {
+    fromState = path.basename(path.dirname(src))
+    targetDir = stateDir(state)
+    if (!targetDir) {
+      console.error(`invalid state "${state}"`)
+      process.exitCode = 1
+      return
+    }
+    logBasename = basename
+  }
 
-  try {
-    fs.mkdirSync(targetDir, { recursive: true })
-  } catch (_) {}
+  try { fs.mkdirSync(targetDir, { recursive: true }) } catch (_) {}
 
   const dst = path.join(targetDir, basename)
   fs.renameSync(src, dst)
 
-  appendTransitionLog(basename, fromState, state)
+  appendTransitionLog(logBasename, fromState, state)
   console.log(`✓ moved ${basename} → ${targetDir}`)
 }
 
 /**
- * appendTransitionLog — append em docs/roadmaps/.trackfw-log.
- * Formato: `YYYY-MM-DD HH:mm  <basename padded to 50>  <fromState> → <toState>\n`
+ * appendTransitionLog — append em <roadmapDir>/.trackfw-log.
  */
 function appendTransitionLog(basename, fromState, toState) {
   const now = new Date()
@@ -135,24 +190,39 @@ function appendTransitionLog(basename, fromState, toState) {
   const line = `${timestamp}  ${basename.padEnd(50)}  ${fromState} → ${toState}\n`
 
   try {
-    fs.mkdirSync(path.dirname(TRANSITION_LOG_PATH), { recursive: true })
-    fs.appendFileSync(TRANSITION_LOG_PATH, line, 'utf8')
+    const lp = logPath()
+    fs.mkdirSync(path.dirname(lp), { recursive: true })
+    fs.appendFileSync(lp, line, 'utf8')
   } catch (_) {}
 }
 
 /**
- * newRoadmap — cria roadmap em docs/roadmaps/backlog/ROADMAP-YYYY-MM-DD-<slug>.md.
+ * newRoadmap — cria roadmap em <roadmapDir>/backlog/ROADMAP-YYYY-MM-DD-<slug>.md.
+ * Em modo by_agent, usa o primeiro agente configurado.
  */
 function newRoadmap(title, reqPath) {
+  const cfg = config.load()
   const now = new Date()
   const yyyy = now.getFullYear()
   const mm = String(now.getMonth() + 1).padStart(2, '0')
   const dd = String(now.getDate()).padStart(2, '0')
   const date = `${yyyy}-${mm}-${dd}`
   const slug = toSlug(title)
-  const filename = `docs/roadmaps/backlog/ROADMAP-${date}-${slug}.md`
 
-  fs.mkdirSync('docs/roadmaps/backlog', { recursive: true })
+  let backlogDir
+  if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
+    backlogDir = agentStateDir(null, 'backlog')
+    if (!backlogDir) {
+      console.error('cannot resolve backlog dir in by_agent mode')
+      process.exitCode = 1
+      return
+    }
+  } else {
+    backlogDir = cfg.roadmapDir + '/backlog'
+  }
+
+  const filename = `${backlogDir}/ROADMAP-${date}-${slug}.md`
+  fs.mkdirSync(backlogDir, { recursive: true })
 
   const body = `# Roadmap: ${title}
 
@@ -183,21 +253,43 @@ REQ: ${reqPath || ''}
 
 /**
  * findRoadmapMatches — retorna array de paths que contêm `name` (case-insensitive) em qualquer estado.
+ * Suporta modo flat (1 nível) e by_agent (2 níveis).
  */
 function findRoadmapMatches(name) {
+  const cfg = config.load()
   const matches = []
   const nameLower = name.toLowerCase()
-  for (const state of STATE_ORDER) {
-    const dir = VALID_STATES[state]
-    let files = []
-    try {
-      files = fs.readdirSync(dir)
-    } catch (_) {
-      continue
+
+  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 = ['default'] }
+    }
+    for (const agent of agents) {
+      for (const state of STATE_ORDER) {
+        const dir = cfg.roadmapDir + '/' + agent + '/' + state
+        let files = []
+        try { files = fs.readdirSync(dir) } catch (_) { continue }
+        for (const f of files) {
+          if (f.toLowerCase().includes(nameLower) && f.endsWith('.md')) {
+            matches.push(path.join(dir, f))
+          }
+        }
+      }
     }
-    for (const f of files) {
-      if (f.toLowerCase().includes(nameLower) && f.endsWith('.md')) {
-        matches.push(path.join(dir, f))
+  } else {
+    for (const state of STATE_ORDER) {
+      const dir = cfg.roadmapDir + '/' + state
+      let files = []
+      try { files = fs.readdirSync(dir) } catch (_) { continue }
+      for (const f of files) {
+        if (f.toLowerCase().includes(nameLower) && f.endsWith('.md')) {
+          matches.push(path.join(dir, f))
+        }
       }
     }
   }
@@ -215,10 +307,11 @@ function toSlug(s) {
 }
 
 module.exports = {
-  VALID_STATES,
   listRoadmaps,
   showRoadmap,
   moveRoadmap,
   appendTransitionLog,
   newRoadmap,
+  stateDir,
+  agentStateDir,
 }

package/src/validator/index.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs')
 const path = require('path')
+const config = require('../config')
 
 const STALE_WIP_DAYS = 7
 
@@ -21,6 +22,22 @@ function listDir(dir) {
   }
 }
 
+// resolveWIPDirs retorna todos os diretórios wip/ conforme o modo de namespacing.
+function resolveWIPDirs(cfg) {
+  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 = [] }
+    }
+    return agents.map(agent => cfg.roadmapDir + '/' + agent + '/wip')
+  }
+  return [cfg.roadmapDir + '/wip']
+}
+
 // parseBlockedADRs extrai basenames de ADRs da seção "## Blocked by ADRs" de um arquivo REQ.
 function parseBlockedADRs(filePath) {
   let content
@@ -51,40 +68,52 @@ function parseBlockedADRs(filePath) {
   return adrs
 }
 
-// adrIsDraft verifica se docs/adr/<basename> contém "Status: Draft".
+// adrIsDraft verifica se <adrBasename> contém "Status: Draft" em alguma das adrDirs configuradas.
 function adrIsDraft(basename) {
-  try {
-    const content = fs.readFileSync(path.join('docs', 'adr', basename), 'utf8')
-    return content.includes('Status: Draft')
-  } catch (_) {
-    return false
+  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
+      }
+    }
   }
+  return false
 }
 
-// validateWIPHasREQ — roadmaps em docs/roadmaps/wip/ sem "REQ:" no conteúdo → violation
+// validateWIPHasREQ — roadmaps em wip/ sem "REQ:" no conteúdo → violation
+// Suporta modo by_agent via resolveWIPDirs.
 function validateWIPHasREQ() {
-  const entries = listDir('docs/roadmaps/wip')
+  const cfg = config.load()
+  const wipDirs = resolveWIPDirs(cfg)
   const violations = []
-  for (const name of entries) {
-    try {
-      const content = fs.readFileSync(path.join('docs/roadmaps/wip', name), 'utf8')
-      if (!content.includes('REQ:') || content.includes('REQ: \n')) {
-        violations.push(`roadmap "${name}" is in wip but has no linked REQ`)
+  for (const wipDir of wipDirs) {
+    const entries = listDir(wipDir)
+    for (const name of entries) {
+      try {
+        const content = fs.readFileSync(path.join(wipDir, name), 'utf8')
+        if (!content.includes('REQ:') || content.includes('REQ: \n')) {
+          violations.push(`roadmap "${name}" is in wip but has no linked REQ`)
+        }
+      } catch (_) {
+        // ignorar erro de leitura
       }
-    } catch (_) {
-      // ignorar erro de leitura
     }
   }
   return violations
 }
 
-// validateREQsHaveADR — REQs em docs/req/ sem "ADR:" no conteúdo → violation
+// validateREQsHaveADR — REQs em <reqDir>/ sem "ADR:" no conteúdo → violation
 function validateREQsHaveADR() {
-  const entries = listDir('docs/req')
+  const cfg = config.load()
+  const entries = listDir(cfg.reqDir)
   const violations = []
   for (const name of entries) {
     try {
-      const content = fs.readFileSync(path.join('docs/req', name), 'utf8')
+      const content = fs.readFileSync(path.join(cfg.reqDir, name), 'utf8')
       if (!content.includes('ADR:') || content.includes('ADR: \n')) {
         violations.push(`req "${name}" has no linked ADR`)
       }
@@ -95,13 +124,14 @@ function validateREQsHaveADR() {
   return violations
 }
 
-// validateBlockedHasREQ — roadmaps em docs/roadmaps/blocked/ sem "REQ:" → violation
+// validateBlockedHasREQ — roadmaps em <roadmapDir>/blocked/ sem "REQ:" → violation
 function validateBlockedHasREQ() {
-  const entries = listDir('docs/roadmaps/blocked')
+  const cfg = config.load()
+  const entries = listDir(cfg.roadmapDir + '/blocked')
   const violations = []
   for (const name of entries) {
     try {
-      const content = fs.readFileSync(path.join('docs/roadmaps/blocked', name), 'utf8')
+      const content = fs.readFileSync(path.join(cfg.roadmapDir + '/blocked', name), 'utf8')
       if (!content.includes('REQ:') || content.includes('REQ: \n')) {
         violations.push(`roadmap "${name}" is in blocked but has no linked REQ`)
       }
@@ -114,11 +144,12 @@ function validateBlockedHasREQ() {
 
 // validateREQsHaveRoadmap — REQs sem "Roadmap:" → violation
 function validateREQsHaveRoadmap() {
-  const entries = listDir('docs/req')
+  const cfg = config.load()
+  const entries = listDir(cfg.reqDir)
   const violations = []
   for (const name of entries) {
     try {
-      const content = fs.readFileSync(path.join('docs/req', name), 'utf8')
+      const content = fs.readFileSync(path.join(cfg.reqDir, name), 'utf8')
       if (!content.includes('Roadmap:') || content.includes('Roadmap: \n')) {
         violations.push(`req "${name}" has no linked Roadmap`)
       }
@@ -129,15 +160,19 @@ function validateREQsHaveRoadmap() {
   return violations
 }
 
-// validateADRsAreReferenced — ADRs em docs/adr/ não referenciados em nenhuma REQ → violation
+// validateADRsAreReferenced — ADRs em adrDirs não referenciados em nenhuma REQ → violation
 function validateADRsAreReferenced() {
-  const adrs = listDir('docs/adr')
-  const reqEntries = listDir('docs/req')
+  const cfg = config.load()
+  let adrs = []
+  for (const adrDir of cfg.adrDirs) {
+    adrs = adrs.concat(listDir(adrDir))
+  }
 
+  const reqEntries = listDir(cfg.reqDir)
   let combined = ''
   for (const name of reqEntries) {
     try {
-      combined += fs.readFileSync(path.join('docs/req', name), 'utf8')
+      combined += fs.readFileSync(path.join(cfg.reqDir, name), 'utf8')
     } catch (_) {
       // ignorar
     }
@@ -153,63 +188,104 @@ function validateADRsAreReferenced() {
 }
 
 // validateWIPHasAcceptanceCriteria — roadmaps wip sem bloco de critérios de aceite → violation
+// Suporta modo by_agent via resolveWIPDirs.
 function validateWIPHasAcceptanceCriteria() {
-  const entries = listDir('docs/roadmaps/wip')
+  const cfg = config.load()
+  const wipDirs = resolveWIPDirs(cfg)
   const violations = []
-  for (const name of entries) {
-    try {
-      const content = fs.readFileSync(path.join('docs/roadmaps/wip', name), 'utf8')
-      const hasBlock =
-        content.includes('## Acceptance Criteria') ||
-        content.includes('## Critérios de Aceite') ||
-        content.includes('acceptance criteria') ||
-        content.includes('Acceptance Criteria:')
-      if (!hasBlock) {
-        violations.push(`roadmap "${name}" is in wip but has no acceptance criteria block`)
+  for (const wipDir of wipDirs) {
+    const entries = listDir(wipDir)
+    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:')
+        if (!hasBlock) {
+          violations.push(`roadmap "${name}" is in wip but has no acceptance criteria block`)
+        }
+      } catch (_) {
+        // ignorar
       }
-    } catch (_) {
-      // ignorar
     }
   }
   return violations
 }
 
-// validateSingleWIP — mais de 1 roadmap em wip → warning
-function validateSingleWIP() {
-  const entries = listDir('docs/roadmaps/wip')
-  if (entries.length > 1) {
-    return [`${entries.length} roadmaps in wip/ (recommended: keep only 1 active at a time)`]
+// validateWIPLimit — mais de wipLimit roadmaps em wip → warning.
+// Em modo by_agent, verifica por agente individualmente.
+function validateWIPLimit() {
+  const cfg = config.load()
+
+  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 = [] }
+    }
+    const warnings = []
+    const limit = cfg.wipLimit > 0 ? cfg.wipLimit : 1
+    for (const agent of agents) {
+      const dir = cfg.roadmapDir + '/' + agent + '/wip'
+      const entries = listDir(dir)
+      if (entries.length > limit) {
+        warnings.push(`${entries.length} roadmaps in wip/ for agent "${agent}" (limit: ${limit})`)
+      }
+    }
+    return warnings
+  }
+
+  const entries = listDir(cfg.roadmapDir + '/wip')
+  const limit = cfg.wipLimit > 0 ? cfg.wipLimit : 1
+  if (entries.length > limit) {
+    return [`${entries.length} roadmaps in wip/ (limit: ${limit})`]
   }
   return []
 }
 
+// validateSingleWIP — alias retrocompatível de validateWIPLimit (modo flat)
+function validateSingleWIP() {
+  return validateWIPLimit()
+}
+
 // validateStaleWIP — roadmaps wip com mtime >= 7 dias → warning
+// Suporta modo by_agent via resolveWIPDirs.
 function validateStaleWIP() {
-  let files = []
-  try {
-    files = fs.readdirSync('docs/roadmaps/wip')
-      .filter(f => f.endsWith('.md'))
-      .map(f => path.join('docs/roadmaps/wip', f))
-  } catch (_) {
-    return []
-  }
-
+  const cfg = config.load()
+  const wipDirs = resolveWIPDirs(cfg)
   const warnings = []
   const now = Date.now()
-  for (const filePath of files) {
+
+  for (const wipDir of wipDirs) {
+    let files = []
     try {
-      const stat = fs.statSync(filePath)
-      const ageMs = now - 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 basename = path.basename(filePath)
-        warnings.push(
-          `roadmap/wip/${basename} has been in WIP for ${days} days (last modified ${lastModified})`
-        )
-      }
+      files = fs.readdirSync(wipDir)
+        .filter(f => f.endsWith('.md'))
+        .map(f => path.join(wipDir, f))
     } catch (_) {
-      // ignorar
+      continue
+    }
+
+    for (const filePath of files) {
+      try {
+        const stat = fs.statSync(filePath)
+        const ageMs = now - 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 basename = path.basename(filePath)
+          warnings.push(
+            `roadmap/wip/${basename} has been in WIP for ${days} days (last modified ${lastModified})`
+          )
+        }
+      } catch (_) {
+        // ignorar
+      }
     }
   }
   return warnings
@@ -217,10 +293,11 @@ function validateStaleWIP() {
 
 // validateREQsNotBlockedByDraftADRs — REQs Open com ADRs Draft na seção "## Blocked by ADRs" → violation
 function validateREQsNotBlockedByDraftADRs() {
-  const entries = listDir('docs/req')
+  const cfg = config.load()
+  const entries = listDir(cfg.reqDir)
   const violations = []
   for (const name of entries) {
-    const filePath = path.join('docs/req', name)
+    const filePath = path.join(cfg.reqDir, name)
     let content
     try {
       content = fs.readFileSync(filePath, 'utf8')
@@ -241,10 +318,11 @@ function validateREQsNotBlockedByDraftADRs() {
 
 // blockedREQs retorna mapa de reqBasename → [adrBasenames Draft] para uso em getStatus()
 function blockedREQs() {
-  const entries = listDir('docs/req')
+  const cfg = config.load()
+  const entries = listDir(cfg.reqDir)
   const result = {}
   for (const name of entries) {
-    const filePath = path.join('docs/req', name)
+    const filePath = path.join(cfg.reqDir, name)
     let content
     try {
       content = fs.readFileSync(filePath, 'utf8')
@@ -274,7 +352,7 @@ async function validate() {
     ...validateREQsNotBlockedByDraftADRs(),
   ]
   const warnings = [
-    ...validateSingleWIP(),
+    ...validateWIPLimit(),
     ...validateStaleWIP(),
   ]
   return { violations, warnings }
@@ -282,40 +360,59 @@ async function validate() {
 
 // getStatus retorna string formatada com o status de governança do projeto
 async function getStatus() {
-  const wip = listDir('docs/roadmaps/wip')
-  const blocked = listDir('docs/roadmaps/blocked')
-  const done = listDir('docs/roadmaps/done')
+  const cfg = config.load()
+  let out = '── trackfw status ──────────────────────\n'
 
-  let out = ''
-  out += '── trackfw status ──────────────────────\n'
+  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 = [] }
+    }
+    out += '\n⚙ WIP by Agent\n'
+    for (const agent of agents) {
+      const wip = listDir(cfg.roadmapDir + '/' + agent + '/wip')
+      if (wip.length > 0) {
+        out += `  [${agent}] WIP (${wip.length})\n`
+        wip.forEach(f => { out += `    ${f}\n` })
+      }
+    }
+  } else {
+    const wip = listDir(cfg.roadmapDir + '/wip')
+    const blocked = listDir(cfg.roadmapDir + '/blocked')
+    const done = listDir(cfg.roadmapDir + '/done')
 
-  out += `\n🔄 WIP (${wip.length})\n`
-  for (const f of wip) out += `   ${f}\n`
+    out += `\n🔄 WIP (${wip.length})\n`
+    for (const f of wip) out += `   ${f}\n`
 
-  out += `\n❌ Blocked (${blocked.length})\n`
-  for (const f of blocked) out += `   ${f}\n`
+    out += `\n❌ Blocked (${blocked.length})\n`
+    for (const f of blocked) out += `   ${f}\n`
 
-  const staleWIPs = validateStaleWIP()
-  if (staleWIPs.length > 0) {
-    out += `\n⚠  Stale WIP (${staleWIPs.length})\n`
-    for (const w of staleWIPs) out += `   ${w}\n`
-  }
+    const staleWIPs = validateStaleWIP()
+    if (staleWIPs.length > 0) {
+      out += `\n⚠  Stale WIP (${staleWIPs.length})\n`
+      for (const w of staleWIPs) out += `   ${w}\n`
+    }
 
-  const blockedByDraft = blockedREQs()
-  const blockedKeys = Object.keys(blockedByDraft)
-  if (blockedKeys.length > 0) {
-    out += `\n⏳ REQs blocked by Draft ADRs (${blockedKeys.length})\n`
-    for (const reqFile of blockedKeys) {
-      out += `   ${reqFile}\n`
-      for (const adr of blockedByDraft[reqFile]) {
-        out += `     → ${adr} (Draft)\n`
+    const blockedByDraft = blockedREQs()
+    const blockedKeys = Object.keys(blockedByDraft)
+    if (blockedKeys.length > 0) {
+      out += `\n⏳ REQs blocked by Draft ADRs (${blockedKeys.length})\n`
+      for (const reqFile of blockedKeys) {
+        out += `   ${reqFile}\n`
+        for (const adr of blockedByDraft[reqFile]) {
+          out += `     → ${adr} (Draft)\n`
+        }
       }
     }
-  }
 
-  out += `\n✅ Done (last 5)\n`
-  const last5 = done.length > 5 ? done.slice(done.length - 5) : done
-  for (const f of last5) out += `   ${f}\n`
+    out += `\n✅ Done (last 5)\n`
+    const last5 = done.length > 5 ? done.slice(done.length - 5) : done
+    for (const f of last5) out += `   ${f}\n`
+  }
 
   out += '\n────────────────────────────────────────\n'
   return out
@@ -331,10 +428,12 @@ module.exports = {
   validateREQsHaveRoadmap,
   validateADRsAreReferenced,
   validateWIPHasAcceptanceCriteria,
+  validateWIPLimit,
   validateSingleWIP,
   validateStaleWIP,
   validateREQsNotBlockedByDraftADRs,
   parseBlockedADRs,
   adrIsDraft,
   listDir,
+  resolveWIPDirs,
 }