trackfw 3.0.0 → 3.1.0

package/src/validator/index.js

@@ -7,6 +7,7 @@ const config = require('../config')
 const { checkTraceIds } = require('./traceid')
 
 const STALE_WIP_DAYS = 7
+let staleWipNowMs = () => Date.now()
 
 // listDir retorna array de nomes de arquivo (não-diretórios) em dir.
 // Retorna [] se o diretório não existir.
@@ -25,6 +26,44 @@ function listDir(dir) {
   }
 }
 
+// tryListDir tenta listar o diretório distinguindo "não existe" de outros erros.
+// Retorna { entries: string[], readError: Error|null }.
+// readError é null tanto no caso de sucesso quanto quando o diretório não existe (ENOENT) —
+// diretório ausente é esperado para estados que o projeto não usa.
+// readError não-null indica que o diretório EXISTE mas não pôde ser lido (ENOTDIR, EPERM…).
+function tryListDir(dir) {
+  const expanded = config.expandPath ? config.expandPath(dir) : dir
+  try {
+    const entries = fs.readdirSync(expanded).filter(name => {
+      try { return !fs.statSync(path.join(expanded, name)).isDirectory() } catch (_) { return false }
+    })
+    return { entries, readError: null }
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { entries: [], readError: null }
+    return { entries: [], readError: err }
+  }
+}
+
+function inspectionDiagnostic(rule, target, err) {
+  const cause = err && err.message ? err.message : String(err)
+  return `${rule}: could not inspect "${target}": ${cause}`
+}
+
+function listDirForRule(rule, dir, messages) {
+  const { entries, readError } = tryListDir(dir)
+  if (readError) messages.push(inspectionDiagnostic(rule, dir, readError))
+  return entries
+}
+
+function readFileForRule(rule, filePath, messages) {
+  try {
+    return fs.readFileSync(filePath, 'utf8')
+  } catch (err) {
+    messages.push(inspectionDiagnostic(rule, filePath, err))
+    return null
+  }
+}
+
 // isInsideDir retorna true se childPath estiver contido ou for igual a parentDir.
 function isInsideDir(parentDir, childPath) {
   if (!parentDir || !childPath) return false
@@ -34,17 +73,28 @@ function isInsideDir(parentDir, childPath) {
 
 // walkDirMdWithPaths retorna { name, fullPath } de todos .md recursivamente dentro de dir.
 function walkDirMdWithPaths(dir) {
+  return walkDirMdWithPathsForRule(null, dir, null)
+}
+
+function walkDirMdWithPathsForRule(rule, dir, messages) {
   const results = []
   const expandedDir = config.expandPath ? config.expandPath(dir) : dir
   function walk(d) {
     let entries
-    try { entries = fs.readdirSync(d) } catch (_) { return }
+    try {
+      entries = fs.readdirSync(d)
+    } catch (err) {
+      if (messages && err && err.code !== 'ENOENT') messages.push(inspectionDiagnostic(rule, d, err))
+      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, fullPath: full }) }
-      } catch (_) {}
+      } catch (err) {
+        if (messages) messages.push(inspectionDiagnostic(rule, full, err))
+      }
     }
   }
   walk(expandedDir)
@@ -104,7 +154,7 @@ function resolveReqFiles(cfg) {
   if (!reqDir) return []
   const namespacing = cfg.roadmapNamespacing || cfg.roadmap_namespacing || ''
   if (namespacing === 'by_agent') {
-    const STATES = ['backlog', 'wip', 'blocked', 'done', 'abandoned']
+    const STATES = ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']
     let agents = cfg.agents || []
     if (!agents.length) {
       try {
@@ -134,8 +184,11 @@ function resolveReqFiles(cfg) {
   } catch (_) { return [] }
 }
 
-// resolveWIPDirs retorna todos os diretórios wip/ conforme o modo de namespacing.
-function resolveWIPDirs(cfg) {
+// resolveStateDirs retorna todos os diretórios de um estado (ex: 'wip', 'done') conforme o modo de
+// namespacing. É a fonte única de resolução de caminho por estado — resolveWIPDirs e resolveDoneDirs
+// são wrappers finos sobre esta função. Duplicar a lógica aqui foi a causa raiz de defeitos
+// anteriores (roadmap_dir divergente entre runtimes).
+function resolveStateDirs(cfg, state) {
   if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
     let agents = cfg.agents || []
     if (agents.length === 0) {
@@ -145,9 +198,19 @@ function resolveWIPDirs(cfg) {
         })
       } catch (_) { agents = [] }
     }
-    return agents.map(agent => cfg.roadmapDir + '/' + agent + '/wip')
+    return agents.map(agent => cfg.roadmapDir + '/' + agent + '/' + state)
   }
-  return [cfg.roadmapDir + '/wip']
+  return [cfg.roadmapDir + '/' + state]
+}
+
+// resolveWIPDirs retorna todos os diretórios wip/ conforme o modo de namespacing.
+function resolveWIPDirs(cfg) {
+  return resolveStateDirs(cfg, 'wip')
+}
+
+// resolveDoneDirs retorna todos os diretórios done/ conforme o modo de namespacing.
+function resolveDoneDirs(cfg) {
+  return resolveStateDirs(cfg, 'done')
 }
 
 // parseBlockedADRs extrai basenames de ADRs da seção "## Blocked by ADRs" de um arquivo REQ.
@@ -181,9 +244,10 @@ function parseBlockedADRs(filePath) {
 }
 
 // contentHasMarker retorna true se o conteúdo contém algum dos markers sem espaço em branco após.
+// P3: verifica tanto "\n" quanto "\r\n" para detectar campos vazios em arquivos CRLF.
 function contentHasMarker(content, markers) {
   for (const marker of markers) {
-    if (content.includes(marker) && !content.includes(marker + ' \n')) {
+    if (content.includes(marker) && !content.includes(marker + ' \n') && !content.includes(marker + ' \r\n')) {
       return true
     }
   }
@@ -192,11 +256,18 @@ function contentHasMarker(content, markers) {
 
 // adrIsDraft verifica se <adrBasename> contém "Status: Draft" buscando recursivamente nas adrDirs.
 function adrIsDraft(basename) {
+  return adrDraftStatusForRule(basename, null).draft
+}
+
+function adrDraftStatusForRule(basename, messages) {
   const p = findAdrFile(basename)
-  if (!p) return false
+  if (!p) return { draft: false, inspected: true }
   try {
-    return fs.readFileSync(p, 'utf8').includes('Status: Draft')
-  } catch (_) { return false }
+    return { draft: fs.readFileSync(p, 'utf8').includes('Status: Draft'), inspected: true }
+  } catch (err) {
+    if (messages) messages.push(inspectionDiagnostic('blocked_by_draft_adr', p, err))
+    return { draft: false, inspected: false }
+  }
 }
 
 // validateWIPHasREQ — roadmaps em wip/ sem marker REQ no conteúdo → violation
@@ -206,15 +277,12 @@ function validateWIPHasREQ() {
   const wipDirs = resolveWIPDirs(cfg)
   const violations = []
   for (const wipDir of wipDirs) {
-    const entries = listDir(wipDir)
+    const entries = listDirForRule('wip_has_req', wipDir, violations)
     for (const name of entries) {
-      try {
-        const content = fs.readFileSync(path.join(wipDir, name), 'utf8')
-        if (!contentHasMarker(content, cfg.linkFields.req)) {
-          violations.push(`roadmap "${name}" is in wip but has no linked REQ`)
-        }
-      } catch (_) {
-        // ignorar erro de leitura
+      const content = readFileForRule('wip_has_req', path.join(wipDir, name), violations)
+      if (content === null) continue
+      if (!contentHasMarker(content, cfg.linkFields.req)) {
+        violations.push(`roadmap "${name}" is in wip but has no linked REQ`)
       }
     }
   }
@@ -242,16 +310,15 @@ function validateREQsHaveADR() {
 // validateBlockedHasREQ — roadmaps em <roadmapDir>/blocked/ sem marker REQ → violation
 function validateBlockedHasREQ() {
   const cfg = config.load()
-  const entries = listDir(cfg.roadmapDir + '/blocked')
   const violations = []
-  for (const name of entries) {
-    try {
-      const content = fs.readFileSync(path.join(cfg.roadmapDir + '/blocked', name), 'utf8')
+  for (const blockedDir of resolveStateDirs(cfg, 'blocked')) {
+    const entries = listDirForRule('blocked_has_req', blockedDir, violations)
+    for (const name of entries) {
+      const content = readFileForRule('blocked_has_req', path.join(blockedDir, name), violations)
+      if (content === null) continue
       if (!contentHasMarker(content, cfg.linkFields.req)) {
         violations.push(`roadmap "${name}" is in blocked but has no linked REQ`)
       }
-    } catch (_) {
-      // ignorar
     }
   }
   return violations
@@ -285,7 +352,7 @@ function validateADRDirsExist() {
     const expanded = config.expandPath ? config.expandPath(adrDir) : adrDir
     const absDir = path.resolve(expanded)
     if (!fs.existsSync(absDir)) {
-      const msg = `adr directory "${adrDir}" does not exist`
+      const msg = `adr_dir "${adrDir}" does not exist`
       if (cfg.strictCiPaths) {
         violations.push(msg)
       } else {
@@ -301,6 +368,7 @@ function validateADRDirsExist() {
 function validateADRsAreReferenced() {
   const cfg = config.load()
   const cwd = process.cwd()
+  const violations = []
   let adrs = []
   for (const adrDir of cfg.adrDirs || []) {
     const expanded = config.expandPath ? config.expandPath(adrDir) : adrDir
@@ -309,7 +377,7 @@ function validateADRsAreReferenced() {
     if (!isInsideDir(cwd, absDir)) {
       continue
     }
-    for (const item of walkDirMdWithPaths(absDir)) {
+    for (const item of walkDirMdWithPathsForRule('adr_orphan', absDir, violations)) {
       if (isInsideDir(cwd, item.fullPath)) {
         adrs.push(item.name)
       }
@@ -319,14 +387,10 @@ function validateADRsAreReferenced() {
   const reqFiles = resolveReqFiles(cfg)
   let combined = ''
   for (const filePath of reqFiles) {
-    try {
-      combined += fs.readFileSync(filePath, 'utf8')
-    } catch (_) {
-      // ignorar
-    }
+    const content = readFileForRule('adr_orphan', filePath, violations)
+    if (content !== null) combined += content
   }
 
-  const violations = []
   for (const adr of adrs) {
     if (!combined.includes(adr)) {
       violations.push(`adr "${adr}" is not referenced by any REQ`)
@@ -342,16 +406,13 @@ function validateWIPHasAcceptanceCriteria() {
   const wipDirs = resolveWIPDirs(cfg)
   const violations = []
   for (const wipDir of wipDirs) {
-    const entries = listDir(wipDir)
+    const entries = listDirForRule('wip_acceptance', wipDir, violations)
     for (const name of entries) {
-      try {
-        const content = fs.readFileSync(path.join(wipDir, name), 'utf8')
-        const hasBlock = contentHasMarker(content, cfg.acceptanceMarkers)
-        if (!hasBlock) {
-          violations.push(`roadmap "${name}" is in wip but has no acceptance criteria block`)
-        }
-      } catch (_) {
-        // ignorar
+      const content = readFileForRule('wip_acceptance', path.join(wipDir, name), violations)
+      if (content === null) continue
+      const hasBlock = contentHasMarker(content, cfg.acceptanceMarkers)
+      if (!hasBlock) {
+        violations.push(`roadmap "${name}" is in wip but has no acceptance criteria block`)
       }
     }
   }
@@ -468,61 +529,99 @@ function validateSingleWIP() {
 
 // validateStaleWIP — roadmaps wip com mtime >= 7 dias → warning
 // Suporta modo by_agent via resolveWIPDirs.
+function roadmapLogIdentity(cfg, filePath) {
+  const basename = path.basename(filePath)
+  if (cfg.roadmapNamespacing !== config.NAMESPACING_BY_AGENT) return basename
+  const agent = path.basename(path.dirname(path.dirname(filePath)))
+  return `${agent}/${basename}`
+}
+
+function parseTransitionLogLine(line) {
+  const fields = String(line).trim().split(/\s+/).filter(Boolean)
+  if (fields.length < 5) return null
+  const timestamp = Date.parse(`${fields[0]}T${fields[1]}:00`)
+  if (Number.isNaN(timestamp)) return null
+  const arrow = fields.findIndex((field, index) => index >= 3 && (field === '→' || field === '->'))
+  if (arrow < 0 || arrow + 1 >= fields.length) return null
+  return { timestamp, name: fields[2], toState: fields[arrow + 1] }
+}
+
+function latestWipTransitionTime(cfg, filePath) {
+  let content
+  const logPath = path.join(cfg.roadmapDir, '.trackfw-log')
+  try {
+    content = fs.readFileSync(logPath, 'utf8')
+  } catch (err) {
+    return { time: null, diagnostics: err && err.code === 'ENOENT' ? [] : [inspectionDiagnostic('stale_wip', logPath, err)] }
+  }
+  const identity = roadmapLogIdentity(cfg, filePath)
+  let latest = null
+  const diagnostics = []
+  for (const line of content.split('\n')) {
+    if (!line.trim()) continue
+    const parsed = parseTransitionLogLine(line)
+    if (!parsed) {
+      diagnostics.push(`stale_wip: invalid support line in "${logPath}": "${line}"`)
+      continue
+    }
+    if (parsed.name !== identity || parsed.toState !== 'wip') continue
+    if (latest === null || parsed.timestamp > latest) latest = parsed.timestamp
+  }
+  return { time: latest, diagnostics }
+}
+
 function validateStaleWIP() {
   const cfg = config.load()
   const wipDirs = resolveWIPDirs(cfg)
   const warnings = []
-  const now = Date.now()
+  const now = staleWipNowMs()
+  const thresholdDays = cfg.staleWipDays > 0 ? cfg.staleWipDays : STALE_WIP_DAYS
 
   for (const wipDir of wipDirs) {
-    let files = []
-    try {
-      files = fs.readdirSync(wipDir)
-        .filter(f => f.endsWith('.md'))
-        .map(f => path.join(wipDir, f))
-    } catch (_) {
-      continue
-    }
+    const files = listDirForRule('stale_wip', wipDir, warnings)
+      .filter(f => f.endsWith('.md'))
+      .map(f => path.join(wipDir, f))
 
     for (const filePath of files) {
       try {
         const stat = fs.statSync(filePath)
-        const gitTime = gitLastModifiedTime(filePath)
-        const ageMs = now - (gitTime !== null ? gitTime : stat.mtimeMs)
+        const logResult = latestWipTransitionTime(cfg, filePath)
+        warnings.push(...logResult.diagnostics)
+        const refTime = logResult.time !== null ? logResult.time : stat.mtimeMs
+        const ageMs = now - refTime
         const days = Math.floor(ageMs / (1000 * 60 * 60 * 24))
-        if (days >= STALE_WIP_DAYS) {
-          const refTime = gitTime !== null ? gitTime : stat.mtimeMs
+        if (days >= thresholdDays) {
           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})`
           )
         }
-      } catch (_) {
-        // ignorar
+      } catch (err) {
+        warnings.push(inspectionDiagnostic('stale_wip', filePath, err))
       }
     }
   }
   return warnings
 }
 
+function setStaleWipNowForTests(fn) {
+  staleWipNowMs = fn || (() => Date.now())
+}
+
 // validateREQsNotBlockedByDraftADRs — REQs Open com ADRs Draft na seção "## Blocked by ADRs" → violation
 function validateREQsNotBlockedByDraftADRs() {
   const cfg = config.load()
   const files = resolveReqFiles(cfg)
   const violations = []
   for (const filePath of files) {
-    let content
-    try {
-      content = fs.readFileSync(filePath, 'utf8')
-    } catch (_) {
-      continue
-    }
+    const content = readFileForRule('blocked_by_draft_adr', filePath, violations)
+    if (content === null) continue
     if (!content.includes('Status: Open')) continue
 
     const blockedADRs = parseBlockedADRs(filePath)
     for (const adrBasename of blockedADRs) {
-      if (adrIsDraft(adrBasename)) {
+      if (adrDraftStatusForRule(adrBasename, violations).draft) {
         violations.push(`REQ ${path.basename(filePath)} is blocked by Draft ADR: ${adrBasename}`)
       }
     }
@@ -631,11 +730,12 @@ function validateFrontmatterPresence() {
 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()
+    const idx = trimmed.indexOf(':')
+    if (idx !== -1 && trimmed.slice(0, idx).trim().toLowerCase() === field.toLowerCase()) {
+      let val = trimmed.slice(idx + 1).trim()
       if (!val || val === '—' || val === '-' || val === '–') return null
       val = val.split(/\s+/)[0]
+      val = val.replace(/^["']|["']$/g, '')
       if (val.endsWith('.md')) return val
     }
   }
@@ -648,33 +748,31 @@ function validateRefTargetsExist() {
   const warnings = []
 
   // Roadmaps em wip e blocked: verificar REQ:
-  const dirs = [...resolveWIPDirs(cfg), cfg.roadmapDir + '/blocked']
+  const dirs = [...resolveWIPDirs(cfg), ...resolveStateDirs(cfg, '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 && !referenceExists(ref, [cfg.reqDir])) {
-          warnings.push(`roadmap "${name}" links to REQ "${ref}" which does not exist`)
-        }
-      } catch (_) {}
+    for (const name of listDirForRule('ref_targets_exist', dir, warnings)) {
+      const content = readFileForRule('ref_targets_exist', path.join(dir, name), warnings)
+      if (content === null) continue
+      const ref = extractRefPath(content, 'REQ')
+      if (ref && !referenceExists(ref, [cfg.reqDir])) {
+        warnings.push(`roadmap "${name}" links to REQ "${ref}" which does not exist`)
+      }
     }
   }
 
   // REQs: verificar ADR: e Roadmap:
   for (const filePath of resolveReqFiles(cfg)) {
-    try {
-      const content = fs.readFileSync(filePath, 'utf8')
-      const name = path.basename(filePath)
-      const adrRef = extractRefPath(content, 'ADR')
-      if (adrRef && !referenceExists(adrRef, cfg.adrDirs)) {
-        warnings.push(`req "${name}" links to ADR "${adrRef}" which does not exist`)
-      }
-      const roadmapRef = extractRefPath(content, 'Roadmap')
-      if (roadmapRef && !referenceExists(roadmapRef, [cfg.roadmapDir])) {
-        warnings.push(`req "${name}" links to Roadmap "${roadmapRef}" which does not exist`)
-      }
-    } catch (_) {}
+    const content = readFileForRule('ref_targets_exist', filePath, warnings)
+    if (content === null) continue
+    const name = path.basename(filePath)
+    const adrRef = extractRefPath(content, 'ADR')
+    if (adrRef && !referenceExists(adrRef, cfg.adrDirs)) {
+      warnings.push(`req "${name}" links to ADR "${adrRef}" which does not exist`)
+    }
+    const roadmapRef = extractRefPath(content, 'Roadmap')
+    if (roadmapRef && !referenceExists(roadmapRef, [cfg.roadmapDir])) {
+      warnings.push(`req "${name}" links to Roadmap "${roadmapRef}" which does not exist`)
+    }
   }
 
   return warnings
@@ -683,10 +781,43 @@ function validateRefTargetsExist() {
 function referenceExists(ref, roots) {
   const expandedRef = config.expandPath ? config.expandPath(ref) : ref
   if (fs.existsSync(expandedRef)) return true
-  const basename = path.basename(ref)
-  for (const root of roots || []) {
-    const expandedRoot = config.expandPath ? config.expandPath(root) : root
-    if (walkDirMd(expandedRoot).some(filePath => path.basename(filePath) === basename)) return true
+  return false
+}
+
+function validateREQRoadmapLifecycle() {
+  const cfg = config.load()
+  const warnings = []
+  for (const filePath of resolveReqFiles(cfg)) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf8')
+      if (!reqStatusIsOpen(content)) continue
+      const ref = extractRefPath(content, 'Roadmap')
+      if (!ref) continue
+      const expandedRef = config.expandPath ? config.expandPath(ref) : ref
+      if (!fs.existsSync(expandedRef)) continue
+      if (path.basename(path.dirname(expandedRef)) === 'done') {
+        warnings.push(`req "${path.basename(filePath)}" is Open but linked Roadmap "${ref}" is in done/`)
+      }
+    } catch (_) {}
+  }
+  return warnings
+}
+
+function reqStatusIsOpen(content) {
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    const idx = trimmed.indexOf(':')
+    if (idx >= 0 && trimmed.slice(0, idx).trim().toLowerCase() === 'status') {
+      return trimmed.slice(idx + 1).trim().replace(/^["']|["']$/g, '').toLowerCase() === 'open'
+    }
+    const marker = '| Status: '
+    const markerIdx = trimmed.indexOf(marker)
+    if (markerIdx >= 0) {
+      let rest = trimmed.slice(markerIdx + marker.length)
+      const pipeIdx = rest.indexOf(' |')
+      if (pipeIdx >= 0) rest = rest.slice(0, pipeIdx)
+      return rest.trim().toLowerCase() === 'open'
+    }
   }
   return false
 }
@@ -695,6 +826,7 @@ function referenceExists(ref, roots) {
 const FOLDER_TO_STATUS = {
   wip:       ['WIP', 'wip', 'In Progress'],
   backlog:   ['Backlog', 'backlog'],
+  analyzing: ['Analyzing', 'analyzing'],
   blocked:   ['Blocked', 'blocked'],
   done:      ['Done', 'done'],
   abandoned: ['Abandoned', 'abandoned'],
@@ -704,7 +836,7 @@ const FOLDER_TO_STATUS = {
 function validateFolderStatusCoherence() {
   const cfg = config.load()
   const warnings = []
-  const states = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
+  const states = ['wip', 'backlog', 'analyzing', 'blocked', 'done', 'abandoned']
 
   let dirs = []
   if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
@@ -726,7 +858,13 @@ function validateFolderStatusCoherence() {
   }
 
   for (const { dir, state } of dirs) {
-    for (const name of listDir(dir).filter(f => f.endsWith('.md'))) {
+    // P2: distinguir "diretório ausente" (esperado) de outros erros (reportar).
+    const { entries, readError } = tryListDir(dir)
+    if (readError) {
+      warnings.push(`folder_status: could not read directory "${dir}": ${readError.message}`)
+      continue
+    }
+    for (const name of entries.filter(f => f.endsWith('.md'))) {
       try {
         const content = fs.readFileSync(path.join(dir, name), 'utf8')
         // Extrair status do frontmatter
@@ -757,9 +895,10 @@ function validateFolderStatusCoherence() {
 // 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 states = ['wip', 'backlog', 'analyzing', 'blocked', 'done', 'abandoned']
   const seen = {}  // filename → [states]
 
+  const listErrors = []
   if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
     let agents = cfg.agents || []
     if (agents.length === 0) {
@@ -769,7 +908,13 @@ function validateFilenameUniqueness() {
     }
     for (const agent of agents) {
       for (const state of states) {
-        for (const name of listDir(path.join(cfg.roadmapDir, agent, state))) {
+        const dir = path.join(cfg.roadmapDir, agent, state)
+        const { entries, readError } = tryListDir(dir)
+        if (readError) {
+          listErrors.push(`filename_uniqueness: could not read directory "${dir}": ${readError.message}`)
+          continue
+        }
+        for (const name of entries) {
           const key = agent + '/' + name
           if (!seen[key]) seen[key] = []
           seen[key].push(state)
@@ -778,23 +923,36 @@ function validateFilenameUniqueness() {
     }
   } else {
     for (const state of states) {
-      for (const name of listDir(path.join(cfg.roadmapDir, state))) {
+      const dir = path.join(cfg.roadmapDir, state)
+      const { entries, readError } = tryListDir(dir)
+      if (readError) {
+        listErrors.push(`filename_uniqueness: could not read directory "${dir}": ${readError.message}`)
+        continue
+      }
+      for (const name of entries) {
         if (!seen[name]) seen[name] = []
         seen[name].push(state)
       }
     }
   }
 
-  const violations = []
-  for (const [name, stateList] of Object.entries(seen)) {
+  const violations = [...listErrors]
+  // P3: ordenar os estados dentro de cada mensagem e as mensagens pelo nome
+  // para garantir saída determinística independente de ordem de inserção.
+  const sortedNames = Object.keys(seen).sort()
+  for (const name of sortedNames) {
+    const stateList = seen[name]
     if (stateList.length > 1) {
-      violations.push(`roadmap "${name}" appears in multiple states: [${stateList.join(', ')}]`)
+      const sortedStates = [...stateList].sort()
+      violations.push(`roadmap "${name}" appears in multiple states: [${sortedStates.join(', ')}]`)
     }
   }
   return violations
 }
 
-// validateBranchHasWIPRoadmap — verifica que branch feat/fix/refactor tem ao menos um roadmap em wip/
+// validateBranchHasWIPRoadmap — verifica que branch feat/fix/refactor tem ao menos um roadmap em
+// wip/ ou done/ cujo slug case com a branch. Aceita done/ para permitir encerramento do roadmap na
+// própria branch, conforme a Definition of Done, sem reprovar o gate.
 function validateBranchHasWIPRoadmap() {
   const { execSync } = require('child_process')
   let branch = process.env.TRACKFW_BRANCH || ''
@@ -815,24 +973,63 @@ function validateBranchHasWIPRoadmap() {
 
   const cfg = config.load()
   const wipDirs = resolveWIPDirs(cfg)
+  const doneDirs = resolveDoneDirs(cfg)
   const branchSlug = normalizeBranchSlug(branch.split('/', 2)[1])
-  const wipFiles = []
-  for (const wipDir of wipDirs) {
-    const files = listDir(wipDir).filter(f => f.endsWith('.md'))
-    wipFiles.push(...files)
+  // candidates reúne todos os roadmaps encontrados em wip/ e done/.
+  const candidates = []
+  for (const dir of [...wipDirs, ...doneDirs]) {
+    const files = listDir(dir).filter(f => f.endsWith('.md'))
+    candidates.push(...files)
     if (files.some(file => normalizeBranchSlug(file).includes(branchSlug))) return []
   }
 
-  if (wipFiles.length === 0) {
-    return [`branch "${branch}" is a feat/fix/refactor branch but no roadmap is in wip/ — create governance artifacts first:\n  trackfw req new "title"\n  trackfw roadmap new "title"\n  trackfw roadmap move <name> wip`]
+  if (candidates.length === 0) {
+    return [`branch "${branch}" is a feat/fix/refactor branch but no roadmap is in wip/ nor done/ — create governance artifacts first:\n  trackfw req new "title"\n  trackfw roadmap new "title"\n  trackfw roadmap move <name> wip`]
   }
-  return [`branch "${branch}" has no matching roadmap in wip/ (found: ${wipFiles.join(', ')}) — include the branch slug in the roadmap filename or set TRACKFW_BRANCH explicitly in CI`]
+  // P3: sort for deterministic output regardless of filesystem ordering.
+  const sorted = [...candidates].sort()
+  const display = sorted.slice(0, 3)
+  const suffix = sorted.length > 3 ? `, e mais ${sorted.length - 3}` : ''
+  return [`branch "${branch}" has no matching roadmap in wip/ nor done/ (found: ${display.join(', ')}${suffix}) — include the branch slug in the roadmap filename or set TRACKFW_BRANCH explicitly in CI`]
 }
 
 function normalizeBranchSlug(value) {
   return String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
 }
 
+/**
+ * Detecta notas em vault/notes/ não referenciadas pelo index.md.
+ * index.md não conta como nota órfã. Projeto sem vault/ retorna [].
+ * Aceita link markdown `[texto](arquivo.md)` ou wikilink `[[nome]]`.
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+function validateNoteOrphan(cwd) {
+  const root = cwd || process.cwd()
+  const vaultDir = path.join(root, 'vault', 'notes')
+  if (!fs.existsSync(vaultDir)) return []
+
+  const indexPath = path.join(vaultDir, 'index.md')
+  let indexContent = ''
+  if (fs.existsSync(indexPath)) {
+    indexContent = fs.readFileSync(indexPath, 'utf8')
+  }
+
+  const notes = fs.readdirSync(vaultDir).filter((f) => f.endsWith('.md') && f !== 'index.md')
+  const msgs = []
+  for (const filename of notes) {
+    const nameWithoutExt = filename.replace(/\.md$/, '')
+    const referenced =
+      indexContent.includes(`(${filename})`) ||
+      indexContent.includes(`[[${nameWithoutExt}]]`) ||
+      indexContent.includes(`[[${filename}]]`)
+    if (!referenced) {
+      msgs.push(`note "${filename}" is not referenced in vault/notes/index.md`)
+    }
+  }
+  return msgs
+}
+
 function isGitWorktree(dir) {
   try {
     const out = execSync('git rev-parse --is-inside-work-tree', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], cwd: dir })
@@ -863,10 +1060,18 @@ function resetMeta() {
   _itemMeta.clear()
 }
 
+// RULE_DEFAULTS mapeia regras cujo default NÃO é 'error'.
+const RULE_DEFAULTS = {
+  note_orphan: 'warning',
+}
+
 // ruleSeverity retorna a severidade configurada para uma regra ('error'|'warning'|'off').
+// Prioridade: trackfw.yaml rules: > RULE_DEFAULTS > 'error'.
 function ruleSeverity(name) {
   const cfg = config.load()
-  return cfg.rules[name] || 'error'
+  if (cfg.rules[name]) return cfg.rules[name]
+  if (RULE_DEFAULTS[name]) return RULE_DEFAULTS[name]
+  return 'error'
 }
 
 // applyRule distribui msgs para violations ou warnings conforme a severidade configurada.
@@ -921,10 +1126,12 @@ async function validateUnfiltered() {
   applyRule('adr_orphan',           validateADRsAreReferenced(),           violations, warnings)
   applyRule('stale_wip',            validateStaleWIP(),                    violations, warnings)
   applyRule('ref_targets_exist',    validateRefTargetsExist(),             violations, warnings)
+  for (const msg of validateREQRoadmapLifecycle()) { _setMeta(msg, 'req_roadmap_lifecycle'); warnings.push(msg) }
   applyRule('folder_status',        validateFolderStatusCoherence(),       violations, warnings)
   applyRule('filename_uniqueness',  validateFilenameUniqueness(),          violations, warnings)
   applyRule('branch_has_wip_roadmap', validateBranchHasWIPRoadmap(),      violations, warnings)
   applyRule('blocked_by_draft_adr', validateREQsNotBlockedByDraftADRs(),  violations, warnings)
+  applyRule('note_orphan',           validateNoteOrphan(),                 violations, warnings)
 
   // Regras configuráveis via applyRule (popula _itemMeta automaticamente)
   applyRule('req_has_adr',          validateREQsHaveADR(),          violations, warnings)
@@ -936,8 +1143,8 @@ async function validateUnfiltered() {
 
   // Validação de existência dos adr_dirs (retorna violations se strictCiPaths, senão warnings)
   const adrDirsExistResult = validateADRDirsExist()
-  for (const msg of adrDirsExistResult.violations) { _setMeta(msg, 'adr_dirs_exist'); violations.push(msg) }
-  for (const msg of adrDirsExistResult.warnings) { _setMeta(msg, 'adr_dirs_exist'); warnings.push(msg) }
+  for (const msg of adrDirsExistResult.violations) { _setMeta(msg, 'adr_dir_exists'); violations.push(msg) }
+  for (const msg of adrDirsExistResult.warnings) { _setMeta(msg, 'adr_dir_exists'); warnings.push(msg) }
 
   // warnings diretos do WIP limit (não configuráveis)
   for (const msg of wipLimitResult.warnings) { _setMeta(msg, 'wip_limit'); warnings.push(msg) }
@@ -1074,10 +1281,12 @@ module.exports = {
   validateWIPLimit,
   validateSingleWIP,
   validateStaleWIP,
+  setStaleWipNowForTests,
   validateREQsNotBlockedByDraftADRs,
   parseBlockedADRs,
   adrIsDraft,
   listDir,
+  tryListDir,
   resolveReqFiles,
   resolveWIPDirs,
   readGovernanceMode,
@@ -1090,6 +1299,7 @@ module.exports = {
   gitLastModifiedTime,
   extractRefPath,
   validateRefTargetsExist,
+  validateREQRoadmapLifecycle,
   validateFolderStatusCoherence,
   validateFilenameUniqueness,
   validateBranchHasWIPRoadmap,