trackfw 7.3.0 → 7.5.0

package/src/validator/index.js

@@ -8,6 +8,28 @@ const { gitOutput } = require('./git-exec')
 const config = require('../config')
 const { checkTraceIds } = require('./traceid')
 const { loadProvenance } = require('../thirdparty/provenance')
+const { homedir } = require('../homedir')
+const { normalizeRefSeparator } = require('../lib/pathfmt')
+const { normalizeCRLF } = require('../integrations/render')
+
+// _platform is seeded from process.platform at module load time. Tests override
+// it via _setPlatformForTest to exercise the Windows guard on any host.
+//
+// Why the mode checks need it: on Windows the POSIX execute bit is not
+// representable on NTFS. fs.statSync().mode & 0o111 is 0 for every regular file,
+// even immediately after fs.chmodSync(path, 0o755). A check written as "the
+// script is not executable" is therefore ALWAYS true there, and no action the
+// user takes can make it false.
+//
+// Mirrors internal/validator/goos.go (Go, canonical) and
+// pypi/trackfw/validator.py (Python).
+let _platform = process.platform
+
+function _setPlatformForTest(plat) {
+  const prev = _platform
+  _platform = plat
+  return () => { _platform = prev }
+}
 
 const STALE_WIP_DAYS = 7
 let staleWipNowMs = () => Date.now()
@@ -60,13 +82,62 @@ function listDirForRule(rule, dir, messages) {
 
 function readFileForRule(rule, filePath, messages) {
   try {
-    return fs.readFileSync(filePath, 'utf8')
+    return readRegularFileSync(filePath).toString('utf8')
   } catch (err) {
     messages.push(inspectionDiagnostic(rule, filePath, err))
     return null
   }
 }
 
+// readRegularFileSync is the fail-safe replacement for fs.readFileSync used by every guard
+// config/script read in this file: validateGuardHookResolvable / validateGuardGlobalHookResolvable,
+// and the *_script_integrity family (validateCredentialGuardScriptIntegrity,
+// validateGitBranchGuardScriptIntegrity, validateGuardGlobalScriptIntegrity).
+// ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio, ML-1C. Port
+// of Go's readRegularFile (internal/validator/regularfile.go) -- see that file's doc comment for
+// the full design rationale.
+//
+// Why: hades-tf's ML-1B barrier found that a FIFO in place of any of these files makes
+// fs.readFileSync block INDEFINITELY (`mkfifo .claude/settings.json` -- `trackfw validate --json`
+// never returns), reproduced live in all 3 runtimes, pre-existing (not introduced by ML-1B).
+//
+// Opens with O_NONBLOCK (where the platform defines the flag -- POSIX only; fs.constants.O_NONBLOCK
+// is undefined on win32, where this degrades to a plain open, matching Go's windows fallback and
+// its documented "reduction, not elimination" caveat for that platform) so a FIFO with no writer on
+// the other end never blocks the open() call itself, then fstats the resulting FILE DESCRIPTOR --
+// not the path -- to confirm what was actually opened is a regular file.
+//
+// Fstat-on-fd is what makes the type check immune to TOCTOU on POSIX: a file descriptor is bound to
+// the inode (or pipe, or device) it was opened against, not to the path string -- whatever happens
+// to the PATH after fs.openSync returns cannot change what fd refers to.
+//
+// Checked via st.isFile(), a POSITIVE allowlist -- every special type (FIFO, socket, char/block
+// device) is excluded by construction, not enumerated one by one.
+//
+// Throws the raw error from fs.openSync unchanged for ordinary open failures (e.g. ENOENT, EACCES)
+// -- callers' existing `e.code === 'ENOENT'` branches keep working exactly as before. Throws a
+// synthetic Error with code 'ENOTFILE' (never 'ENOENT') when the opened fd is not a regular file --
+// this flows into the SAME "not ENOENT" accusing branch every caller already has, no new branch
+// needed anywhere.
+function readRegularFileSync(filePath) {
+  const nonblock = typeof fs.constants.O_NONBLOCK === 'number' ? fs.constants.O_NONBLOCK : 0
+  const fd = fs.openSync(filePath, fs.constants.O_RDONLY | nonblock)
+  try {
+    const st = fs.fstatSync(fd)
+    if (!st.isFile()) {
+      const err = new Error(`${filePath} is not a regular file`)
+      err.code = 'ENOTFILE'
+      throw err
+    }
+    // raw-read-allowed: this IS the fail-safe primitive (readRegularFileSync) — reads from the
+    // already-fstat-confirmed-regular file descriptor `fd`, not from a path.
+    // raw-read-allowed: fd-based, not path-based — the FIFO-hang/TOCTOU class this file exists to close does not apply here.
+    return fs.readFileSync(fd)
+  } finally {
+    fs.closeSync(fd)
+  }
+}
+
 // isInsideDir retorna true se childPath estiver contido ou for igual a parentDir.
 function isInsideDir(parentDir, childPath) {
   if (!parentDir || !childPath) return false
@@ -147,41 +218,288 @@ function gitLastModifiedTime(filePath) {
   return null
 }
 
-// resolveReqFiles retorna array de paths completos de arquivos .md de REQs.
-// Em modo by_agent percorre reqDir/<agente>/<estado>/; em modo flat varre reqDir/ diretamente.
+// resolveAgentNamespaces é o resolvedor canônico de namespaces em modo by_agent — o ÚNICO lugar do
+// módulo onde a lista `agents:` do trackfw.yaml é lida ao lado do disco. Devolve a UNIÃO entre
+// cfg.agents (na ordem declarada, deduplicada) e os subdiretórios de primeiro nível encontrados em
+// dir (ordenados). Todo outro ponto do módulo que precisar enumerar agentes DEVE chamar esta função
+// — nunca reimplementar "if (!agents.length) { ler disco }": esse padrão SUBSTITUÍA o disco em vez
+// de complementá-lo, deixando invisível qualquer namespace em disco não declarado em agents:
+// (REQ-2026-08-29). O padrão `!agents.length`/`agents.length === 0` só pode existir aqui dentro.
+//
+// Segurança — NÃO segue symlink (AC12/AC13, bloqueante): usa fs.readdirSync(dir, {withFileTypes:
+// true}) + dirent.isDirectory(), que reflete o tipo da própria entrada do diretório, não o alvo do
+// link — um namespace que é symlink para fora do projeto nunca é tratado como diretório aqui. NÃO
+// trocar por fs.statSync (que SEGUE symlink e reproduziu ao vivo escrita fora do projeto via
+// `roadmap move` — ver ADR-2026-08-29, decisão 5, e
+// vault/notes/update-segue-symlink-e-escreve-fora-do-projeto-2026-08-28.md).
+function resolveAgentNamespaces(cfg, dir) {
+  const declared = cfg.agents || []
+  const seen = new Set()
+  const ordered = []
+  for (const a of declared) {
+    if (!a || seen.has(a)) continue
+    seen.add(a)
+    ordered.push(a)
+  }
+
+  let entries = []
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true })
+  } catch (_) {
+    return ordered
+  }
+  const fromDisk = entries
+    .filter(e => e.isDirectory()) // symlinks retornam false aqui — nunca seguidos (AC12/AC13)
+    .map(e => e.name)
+    .filter(name => !isInfraDirName(name)) // ML-2A: nunca vira namespace, ver comentário na função
+    .sort()
+  for (const name of fromDisk) {
+    if (seen.has(name)) continue
+    seen.add(name)
+    ordered.push(name)
+  }
+  return ordered
+}
+
+// isInfraDirName decide, no ponto único de leitura de disco do resolvedor, se uma entrada é
+// COMPROVADAMENTE infraestrutura e nunca um namespace de agente — filtrada da união (decisão 1 do
+// ADR) e portanto invisível a todo consumidor.
+//
+// CORREÇÃO (ML-4A, achado 1 do parecer hades-tf 2026-08-30, REPROVA original — espelha
+// internal/validator/validator.go, ver o comentário lá para a justificativa completa): esta lista já
+// incluiu "qualquer nome iniciando com '.'", reabrindo a invisibilidade que a REQ existe para fechar
+// (um namespace real ".ghost" desaparecia de union, status, wip limit e `move` sem sinal algum — um
+// canal de ocultação deliberada). A lista fechada agora tem UMA entrada:
+//   - "node_modules": artefato de tooling JS. Nenhum operador digita isto como nome de agente por
+//     acidente ou por design — ruído inequívoco, sem a ambiguidade de um nome iniciado por ponto.
+// Nomes iniciados por "." NÃO são mais filtrados aqui — continuam entrando na união (nunca
+// invisíveis) — mas o sinal de "não declarado" é rebaixado de violação para aviso de baixo ruído
+// (ver isDotPrefixedName / hiddenNamespaceWarnings), nunca zero sinal.
+function isInfraDirName(name) {
+  return name === 'node_modules'
+}
+
+// isDotPrefixedName reporta se name começa com "." — sinal ambíguo (pode ser um namespace legítimo,
+// ou tooling que nunca deveria estar dentro de roadmapDir/reqDir), não mais um filtro de
+// invisibilidade (ver isInfraDirName). Só rebaixa "não declarado em agents:" de violação para aviso.
+function isDotPrefixedName(name) {
+  return name.startsWith('.')
+}
+
+// AGENT_NAMESPACE_STATE_NAMES replica, só para esta regra, os 6 nomes de estado reservados de
+// roadmap/REQ. Um diretório com um desses nomes no topo de roadmap_dir/req_dir é, na prática, resto
+// de migração incompleta flat→by_agent (ex.: "wip" órfão) — não um agente. A união (decisão 1 do
+// ADR) continua enumerando esses diretórios normalmente — nada fica invisível —, mas eles NÃO
+// disparam validateAgentNamespaceUndeclared: pedir para declarar "wip" como agente em agents: seria
+// ruído confuso, não uma correção real (ML-0A, seção 3, item 3; recomendação adotada sem alteração).
+// Esta exclusão vive só aqui, não no resolvedor — a colisão de nome não é "comprovadamente
+// infraestrutura" como isInfraDirName, é uma inferência sobre o significado do nome, então só afeta
+// a violação, nunca a união/enumeração.
+const AGENT_NAMESPACE_STATE_NAMES = new Set(['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned'])
+
+// undeclaredNamespacesOnDisk devolve, a partir do resolvedor canônico (que já filtra infra e não
+// segue symlink), os nomes de namespace presentes em dir e ausentes de agents:, excluindo colisões
+// com nome de estado reservado (AGENT_NAMESPACE_STATE_NAMES).
+function undeclaredNamespacesOnDisk(cfg, dir, declared) {
+  const out = []
+  for (const name of resolveAgentNamespaces(cfg, dir)) {
+    if (declared.has(name) || AGENT_NAMESPACE_STATE_NAMES.has(name) || isDotPrefixedName(name)) continue
+    out.push(name)
+  }
+  return out
+}
+
+// dotPrefixedUndeclaredOnDisk é o espelho de undeclaredNamespacesOnDisk para o caso ambíguo (nome
+// iniciado por "."): mesmo resolvedor canônico, mesma exclusão de nomes já declarados, mas mantendo
+// exatamente os nomes que undeclaredNamespacesOnDisk descarta por causa do ponto.
+function dotPrefixedUndeclaredOnDisk(cfg, dir, declared) {
+  const out = []
+  for (const name of resolveAgentNamespaces(cfg, dir)) {
+    if (declared.has(name) || !isDotPrefixedName(name)) continue
+    out.push(name)
+  }
+  return out
+}
+
+// validateAgentNamespaceUndeclared implementa a regra "agent_namespace_undeclared"
+// (ADR-2026-08-29, decisão 2 / REQ AC4, AC5, AC9): em modo by_agent, um namespace presente em disco
+// (roadmapDir e/ou reqDir — AC2 estende a união às duas árvores, e esta violação segue) e ausente de
+// agents: é VIOLAÇÃO, não aviso — usa o mesmo default 'error' de toda regra sem entrada em
+// RULE_DEFAULTS (diskRuleSeverity).
+//
+// A união já garante (Wave 1) que o namespace continua sendo ENUMERADO por todo consumidor mesmo com
+// esta violação ativa — esta função só ADICIONA o sinal de configuração incompleta, nunca CONDICIONA
+// a enumeração a ele (AC5-b).
+//
+// Deduplicação por namespace, não por árvore: o caso motivador (cmdb, "zeus" ausente de agents: e em
+// disco em roadmapDir E reqDir ao mesmo tempo) produziria duas violações quase-idênticas se o laço
+// fosse por árvore — ruído no caso comum, não no caso raro. Uma violação por nome, nomeando todas as
+// árvores onde ele foi encontrado.
+function validateAgentNamespaceUndeclared(cfg) {
+  if (cfg.roadmapNamespacing !== config.NAMESPACING_BY_AGENT) return []
+  const declared = new Set(cfg.agents || [])
+
+  const roadmapNames = undeclaredNamespacesOnDisk(cfg, cfg.roadmapDir, declared)
+  const reqNames = undeclaredNamespacesOnDisk(cfg, cfg.reqDir || cfg.req_dir || '', declared)
+
+  const inRoadmap = new Set(roadmapNames)
+  const inReq = new Set(reqNames)
+
+  const names = []
+  const seen = new Set()
+  for (const n of [...roadmapNames, ...reqNames]) {
+    if (seen.has(n)) continue
+    seen.add(n)
+    names.push(n)
+  }
+  names.sort()
+
+  const msgs = []
+  for (const name of names) {
+    const trees = []
+    if (inRoadmap.has(name)) trees.push('roadmap_dir')
+    if (inReq.has(name)) trees.push('req_dir')
+    msgs.push(`agent namespace "${name}" exists in ${trees.join(', ')} but is not declared in agents: — add it to trackfw.yaml`)
+  }
+  return msgs
+}
+
+// hiddenNamespaceWarnings implementa a regra "agent_namespace_hidden" — o contraponto de baixo ruído
+// de validateAgentNamespaceUndeclared para nomes iniciados por "." (ML-4A, achado 1 do parecer
+// hades-tf 2026-08-30). Um diretório oculto/ambíguo em disco (roadmapDir e/ou reqDir), ausente de
+// agents:, NÃO é filtrado da união (resolveAgentNamespaces mantém) e NÃO dispara a violação plena —
+// mas também não é silêncio total: esta função emite um aviso nomeando explicitamente o diretório.
+function hiddenNamespaceWarnings(cfg) {
+  if (cfg.roadmapNamespacing !== config.NAMESPACING_BY_AGENT) return []
+  const declared = new Set(cfg.agents || [])
+
+  const roadmapNames = dotPrefixedUndeclaredOnDisk(cfg, cfg.roadmapDir, declared)
+  const reqNames = dotPrefixedUndeclaredOnDisk(cfg, cfg.reqDir || cfg.req_dir || '', declared)
+
+  const inRoadmap = new Set(roadmapNames)
+  const inReq = new Set(reqNames)
+
+  const names = []
+  const seen = new Set()
+  for (const n of [...roadmapNames, ...reqNames]) {
+    if (seen.has(n)) continue
+    seen.add(n)
+    names.push(n)
+  }
+  names.sort()
+
+  const msgs = []
+  for (const name of names) {
+    const trees = []
+    if (inRoadmap.has(name)) trees.push('roadmap_dir')
+    if (inReq.has(name)) trees.push('req_dir')
+    msgs.push(`dot-prefixed directory "${name}" found in ${trees.join(', ')} is treated as an agent namespace (fully enumerated, not declared in agents:) — declare it in trackfw.yaml if intentional, or remove it if it is leftover tooling`)
+  }
+  return msgs
+}
+
+// REQ_LAYOUT_STATES é a lista fechada de nomes de pasta de ESTADO reconhecidos nos layouts LEGADOS
+// de REQ. Existe só para o leitor tolerar árvores antigas: pelo invariante D1 da ADR-2026-09-03,
+// REQ NÃO tem dimensão de estado. Nada aqui decide onde ESCREVER uma REQ.
+const REQ_LAYOUT_STATES = ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']
+
+// listReqMdFiles lista os .md diretamente dentro de dir (sem recursão, sem seguir para subpastas).
+// Não usa glob: nomes de agente vêm do disco e metacaracteres ("*", "[") corromperiam a contagem.
+function listReqMdFiles(dir) {
+  try {
+    return fs.readdirSync(dir)
+      .filter(n => n.endsWith('.md'))
+      .filter(n => { try { return !fs.statSync(path.join(dir, n)).isDirectory() } catch (_) { return false } })
+      .map(n => path.join(dir, n))
+  } catch (_) { return [] }
+}
+
+// reqWriteDir é o PONTO ÚNICO que decide ONDE uma REQ nova é gravada (ADR-2026-09-03, D2/D4):
+//   flat     → req_dir/
+//   by_agent → req_dir/<agente>/   (primeiro de agents:, ou "default" se a lista é vazia)
+// Consumido pelo gerador (newREQ); a união de leitura abaixo contém este diretório por construção.
+function reqWriteDir(cfg) {
+  const reqDir = cfg.reqDir || cfg.req_dir || ''
+  if (!reqDir) return ''
+  const namespacing = cfg.roadmapNamespacing || cfg.roadmap_namespacing || ''
+  if (namespacing === 'by_agent') {
+    const agents = (cfg.agents || []).filter(a => a)
+    const agent = agents.length > 0 ? agents[0] : 'default'
+    return path.join(reqDir, agent)
+  }
+  return reqDir
+}
+
+// resolveReqFiles é o PONTO ÚNICO de LEITURA de REQ (ADR-2026-09-03, D3/D4): devolve os paths de
+// todos os .md de REQ como UNIÃO dos 4 layouts suportados, nunca como escolha exclusiva:
+//   req_dir/*.md                    flat legado
+//   req_dir/<estado>/*.md           por-estado legado (apesar de D1)
+//   req_dir/<agente>/*.md           CANÔNICO em by_agent
+//   req_dir/<agente>/<estado>/*.md  legado
+// Os dois últimos só valem em by_agent — fora dele não há noção de namespace de agente.
+//
+// Deduplicação é OBRIGATÓRIA: resolveAgentNamespaces devolve agents: ∪ disco, então um
+// req_dir/backlog/ real entra na lista de agentes e o caso <agente>/*.md emite os mesmos paths do
+// caso <estado>/*.md — sem o Set, toda REQ em layout por-estado seria contada (e violada) em dobro.
+// Ordenação final: determinismo igual ao Go/Python (readdirSync não é ordenado por contrato).
 function resolveReqFiles(cfg) {
   const reqDir = cfg.reqDir || cfg.req_dir || ''
   if (!reqDir) return []
   const namespacing = cfg.roadmapNamespacing || cfg.roadmap_namespacing || ''
+  const seen = new Set()
+  const files = []
+  const add = (paths) => {
+    for (const p of paths) {
+      const clean = path.normalize(p)
+      if (seen.has(clean)) continue
+      seen.add(clean)
+      files.push(clean)
+    }
+  }
+
+  // 🔴 §4 (hades-tf 2026-09-03): a dedup por STRING não vê req_dir/Backlog ≡ req_dir/backlog em
+  // filesystem case-INSENSITIVE (APFS, NTFS) — "Backlog" entra na lista de agentes pelo disco e
+  // emite req_dir/Backlog/*.md, enquanto o laço de estados emite req_dir/backlog/*.md hardcoded em
+  // minúscula. Mesmo diretório, strings diferentes: toda REQ contada em DOBRO (medido em APFS:
+  // 2 REQs e 4 violações para 1 arquivo real). Verde no CI Linux, vermelho na máquina do dev.
+  //
+  // MECANISMO: só enumeramos um candidato de subdiretório se o nome existir VERBATIM na listagem do
+  // pai — a grafia do disco é a autoridade, medimos o disco em vez de presumir a propriedade do FS.
+  //   - NÃO troca dupla contagem por SUPRESSÃO: em FS case-SENSITIVE o readdir lista "Backlog" E
+  //     "backlog" (dois diretórios reais distintos) e ambos seguem enumerados. Lowercase colapsaria.
+  //   - NÃO usa ino/dev: fs.statSync().ino não tem contrato medido em NTFS, e ino colidente
+  //     colapsaria arquivos distintos — supressão, a direção proibida.
+  //   - Cobre também NFC/NFD, que case-folding não cobre.
+  //   - FALLBACK É JOIN CEGO, NUNCA LISTA VAZIA: pai ilegível → não filtra nada (dupla contagem
+  //     benigna). Devolver vazio seria supressão.
+  //   - Não filtra por TIPO: um <estado> que seja symlink segue enumerado como antes (§3 é outro
+  //     escopo).
+  // Paridade: mesma lógica em internal/validator/validator.go e pypi/trackfw/validator.py.
+  const childCache = new Map()
+  const hasChildVerbatim = (parent, name) => {
+    if (!childCache.has(parent)) {
+      try { childCache.set(parent, new Set(fs.readdirSync(parent))) } catch (_) { childCache.set(parent, null) }
+    }
+    const children = childCache.get(parent)
+    return children === null ? true : children.has(name)
+  }
+  const addChild = (parent, name) => {
+    if (!hasChildVerbatim(parent, name)) return
+    add(listReqMdFiles(path.join(parent, name)))
+  }
+
+  add(listReqMdFiles(reqDir))
+  for (const state of REQ_LAYOUT_STATES) addChild(reqDir, state)
+
   if (namespacing === 'by_agent') {
-    const STATES = ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']
-    let agents = cfg.agents || []
-    if (!agents.length) {
-      try {
-        agents = fs.readdirSync(reqDir).filter(e => {
-          try { return fs.statSync(path.join(reqDir, e)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) { return [] }
-    }
-    const files = []
-    for (const agent of agents) {
-      for (const state of STATES) {
-        const dir = path.join(reqDir, agent, state)
-        try {
-          for (const name of fs.readdirSync(dir)) {
-            if (name.endsWith('.md')) files.push(path.join(dir, name))
-          }
-        } catch (_) {}
-      }
+    for (const agent of resolveAgentNamespaces(cfg, reqDir)) {
+      addChild(reqDir, agent)
+      for (const state of REQ_LAYOUT_STATES) addChild(path.join(reqDir, agent), state)
     }
-    return files
   }
-  // flat (comportamento anterior) — retorna paths completos
-  try {
-    return fs.readdirSync(reqDir)
-      .filter(n => n.endsWith('.md') && !fs.statSync(path.join(reqDir, n)).isDirectory())
-      .map(n => path.join(reqDir, n))
-  } catch (_) { return [] }
+
+  files.sort()
+  return files
 }
 
 // resolveStateDirs retorna todos os diretórios de um estado (ex: 'wip', 'done') conforme o modo de
@@ -190,14 +508,7 @@ function resolveReqFiles(cfg) {
 // 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) {
-      try {
-        agents = fs.readdirSync(cfg.roadmapDir).filter(f => {
-          try { return fs.statSync(path.join(cfg.roadmapDir, f)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) { agents = [] }
-    }
+    const agents = resolveAgentNamespaces(cfg, cfg.roadmapDir)
     return agents.map(agent => cfg.roadmapDir + '/' + agent + '/' + state)
   }
   return [cfg.roadmapDir + '/' + state]
@@ -214,10 +525,19 @@ function resolveDoneDirs(cfg) {
 }
 
 // parseBlockedADRs extrai basenames de ADRs da seção "## Blocked by ADRs" de um arquivo REQ.
+//
+// ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio, ML-1H:
+// content is folded through normalizeCRLF (npm/src/integrations/render.js) before the exact
+// `line === '## Blocked by ADRs'` comparison below -- same fix, same reason, as Go's
+// parseBlockedADRs (internal/validator/validator.go) and Python's _parse_blocked_adrs
+// (pypi/trackfw/validator.py): a REQ with CRLF (Windows author, or git checkout with
+// core.autocrlf=true -- ADR-2026-09-04 D1's exact scenario) leaves a trailing "\r" on this line
+// after content.split('\n'), and the exact-equality match silently never fires without this.
+// Measured first in the Python port on Windows ARM64; closed identically in all 3 runtimes here.
 function parseBlockedADRs(filePath) {
   let content
   try {
-    content = fs.readFileSync(filePath, 'utf8')
+    content = normalizeCRLF(readRegularFileSync(filePath).toString('utf8'))
   } catch (_) {
     return []
   }
@@ -245,6 +565,9 @@ 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.
+//
+// Usada apenas para markers de "existência de bloco" (ex: acceptanceMarkers, um heading de
+// seção) — não para markers de link (REQ:/ADR:/Roadmap:), que usam contentHasMarkerValue.
 function contentHasMarker(content, markers) {
   for (const marker of markers) {
     if (content.includes(marker) && !content.includes(marker + ' \n') && !content.includes(marker + ' \r\n')) {
@@ -254,6 +577,65 @@ function contentHasMarker(content, markers) {
   return false
 }
 
+// contentHasMarkerValue retorna true se, em alguma LINHA de content, um dos markers aparece
+// logo após espaços/tabs de indentação (nunca no meio de uma frase) e é seguido de um valor
+// substantivo na mesma linha — não vazio e não um comentário HTML disfarçado de valor.
+//
+// issue #278 (achado A2 da auditoria externa, 2026-09-05): a versão anterior buscava o marker
+// como SUBSTRING em qualquer lugar do conteúdo. Isso produzia dois defeitos medidos no acervo
+// mergeado:
+//  1. prosa que menciona o marker no meio de uma frase contava como vínculo real
+//     ("veja a secao ADR: mais abaixo" → true, sem nenhum vínculo).
+//  2. um comentário HTML usado como placeholder contava como valor
+//     ("ADR: <!-- preencher depois -->" → true, campo de fato vazio).
+//
+// Ambos se resolvem tratando a detecção por LINHA em vez de por substring do documento inteiro:
+// o marker só conta quando é a primeira coisa não-branca da linha (tolera espaços/tabs à
+// esquerda, não tolera qualquer outra decoração — "> ", "- ", "# ", "**" não contam como início).
+// Medido antes de decidir (não assumido): nas quatro pastas realmente varridas por estas 4
+// regras (REQ files para ADR:/Roadmap:; roadmaps de wip/blocked para REQ:), a contagem de linhas
+// com decoração diferente de espaço em branco antes do marker é ZERO — os três geradores
+// canônicos sempre emitem o marker no início da linha. Restringir a espaço/tab não introduz
+// falso-positivo novo neste acervo.
+//
+// NÃO resolve (fora de escopo desta ML): "REQ (**reaberta**):" — decoração ENTRE o nome do
+// campo e ":", não ANTES do marker. A literal "REQ:" não aparece nessa linha nem por
+// substring nem por prefixo; ancorar por linha não causa nem cura esse caso. A forma que
+// funciona hoje é "REQ: docs/req/x.md (reaberta)" — o marker intacto, a anotação depois.
+//
+// "none", "TBD", "N/A", "-" continuam sendo tratados como VALOR (não como placeholder). Nenhum
+// dos quatro casos exigidos por esta ML os menciona, e "none" é usado deliberadamente em
+// scripts/check-gates-falsify.sh como placeholder inofensivo — para dizer "sem vínculo real,
+// de propósito" nos fixtures que testam OUTRA regra — sem ficar vazio nem virar comentário
+// HTML. Bloqueá-los moveria a contagem do acervo por um motivo alheio ao achado A2 e quebraria
+// cenários de falsificação que dependem desse contrato.
+//
+// issue #278 (ML-1B): 5 de 7 grafias naturais de campo vazio escapavam da checagem anterior
+// por literal — esta função decide por VALOR (trim do resto da linha), o que já cobre as 7
+// grafias medidas na triagem original.
+function contentHasMarkerValue(content, markers) {
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine
+    const leading = line.replace(/^[ \t]+/, '')
+    for (const marker of markers) {
+      if (!leading.startsWith(marker)) continue
+      const rest = leading.slice(marker.length).trim()
+      if (rest === '') continue
+      if (isHTMLCommentOnlyValue(rest)) continue
+      return true
+    }
+  }
+  return false
+}
+
+// isHTMLCommentOnlyValue retorna true se value (já sem espaços nas duas pontas) é inteiramente
+// um comentário HTML — "<!-- ... -->" do início ao fim, sem nada fora dele. É a forma medida no
+// achado A2: "ADR: <!-- preencher depois -->" é sintaticamente um valor, mas semanticamente um
+// placeholder de "ainda não preenchido" — mesma intenção de um campo vazio, só que disfarçado.
+function isHTMLCommentOnlyValue(value) {
+  return value.startsWith('<!--') && value.endsWith('-->')
+}
+
 // extractAdrHeaderStatus extrai o valor declarado na linha de cabeçalho
 // ("> Date: ... | Status: X") de um ADR. Ancorado à linha — não é substring livre sobre o
 // documento inteiro — para não confundir texto de prosa que mencione "Status: Draft"/"Proposed"
@@ -323,7 +705,7 @@ function adrNotAcceptedStatusForRule(rule, basename, messages) {
   const p = findAdrFile(basename)
   if (!p) return { notAccepted: false, status: '', inspected: true }
   try {
-    const content = fs.readFileSync(p, 'utf8')
+    const content = readRegularFileSync(p).toString('utf8')
     const status = resolveAdrStatus(content)
     const notAccepted = status.toLowerCase() === 'draft' || status.toLowerCase() === 'proposed'
     return { notAccepted, status, inspected: true }
@@ -356,8 +738,8 @@ function validateWIPHasREQ() {
     for (const name of entries) {
       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`)
+      if (!contentHasMarkerValue(content, cfg.linkFields.req)) {
+        violations.push(`roadmap "${name}" is in wip but has no linked REQ (marker must start the line with a real, non-placeholder value)`)
       }
     }
   }
@@ -370,13 +752,10 @@ function validateREQsHaveADR() {
   const files = resolveReqFiles(cfg)
   const violations = []
   for (const filePath of files) {
-    try {
-      const content = fs.readFileSync(filePath, 'utf8')
-      if (!contentHasMarker(content, cfg.linkFields.adr)) {
-        violations.push(`req "${path.basename(filePath)}" has no linked ADR`)
-      }
-    } catch (_) {
-      // ignorar
+    const content = readFileForRule('req_has_adr', filePath, violations)
+    if (content === null) continue
+    if (!contentHasMarkerValue(content, cfg.linkFields.adr)) {
+      violations.push(`req "${path.basename(filePath)}" has no linked ADR (marker must start the line with a real, non-placeholder value)`)
     }
   }
   return violations
@@ -391,8 +770,8 @@ function validateBlockedHasREQ() {
     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`)
+      if (!contentHasMarkerValue(content, cfg.linkFields.req)) {
+        violations.push(`roadmap "${name}" is in blocked but has no linked REQ (marker must start the line with a real, non-placeholder value)`)
       }
     }
   }
@@ -405,13 +784,10 @@ function validateREQsHaveRoadmap() {
   const files = resolveReqFiles(cfg)
   const violations = []
   for (const filePath of files) {
-    try {
-      const content = fs.readFileSync(filePath, 'utf8')
-      if (!contentHasMarker(content, cfg.linkFields.roadmap)) {
-        violations.push(`req "${path.basename(filePath)}" has no linked Roadmap`)
-      }
-    } catch (_) {
-      // ignorar
+    const content = readFileForRule('req_has_roadmap', filePath, violations)
+    if (content === null) continue
+    if (!contentHasMarkerValue(content, cfg.linkFields.roadmap)) {
+      violations.push(`req "${path.basename(filePath)}" has no linked Roadmap (marker must start the line with a real, non-placeholder value)`)
     }
   }
   return violations
@@ -505,7 +881,7 @@ function wipConfigFrom(cfg) {
 function parseSquadFromFrontmatter(filePath) {
   let content
   try {
-    content = fs.readFileSync(filePath, 'utf8')
+    content = readRegularFileSync(filePath).toString('utf8')
   } catch (_) {
     return ''
   }
@@ -526,14 +902,7 @@ function validateWIPLimit() {
   const warnings = []
 
   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 agents = resolveAgentNamespaces(cfg, cfg.roadmapDir)
     const limit = cfg.wipLimit > 0 ? cfg.wipLimit : 1
     for (const agent of agents) {
       const entries = listDir(cfg.roadmapDir + '/' + agent + '/wip')
@@ -606,7 +975,7 @@ function latestWipTransitionTime(cfg, filePath) {
   let content
   const logPath = path.join(cfg.roadmapDir, '.trackfw-log')
   try {
-    content = fs.readFileSync(logPath, 'utf8')
+    content = readRegularFileSync(logPath).toString('utf8')
   } catch (err) {
     return { time: null, diagnostics: err && err.code === 'ENOENT' ? [] : [inspectionDiagnostic('stale_wip', logPath, err)] }
   }
@@ -743,7 +1112,7 @@ function blockedREQs() {
   for (const filePath of files) {
     let content
     try {
-      content = fs.readFileSync(filePath, 'utf8')
+      content = readRegularFileSync(filePath).toString('utf8')
     } catch (_) {
       continue
     }
@@ -796,23 +1165,21 @@ function validateFrontmatterPresence() {
     for (const f of walkDirMd(adrDir)) {
       const fullPath = findAdrFile(f)
       if (!fullPath) continue
-      try {
-        const content = fs.readFileSync(fullPath, 'utf8')
-        if (!content.startsWith('---')) {
-          violations.push(`adr "${f}" has no frontmatter block`)
-        }
-      } catch (_) {}
+      const content = readFileForRule('frontmatter_presence', fullPath, violations)
+      if (content === null) continue
+      if (!content.startsWith('---')) {
+        violations.push(`adr "${f}" has no frontmatter block`)
+      }
     }
   }
 
   const reqFilePaths = resolveReqFiles(cfg)
   for (const filePath of reqFilePaths) {
-    try {
-      const content = fs.readFileSync(filePath, 'utf8')
-      if (!content.startsWith('---')) {
-        violations.push(`req "${path.basename(filePath)}" has no frontmatter block`)
-      }
-    } catch (_) {}
+    const content = readFileForRule('frontmatter_presence', filePath, violations)
+    if (content === null) continue
+    if (!content.startsWith('---')) {
+      violations.push(`req "${path.basename(filePath)}" has no frontmatter block`)
+    }
   }
 
   return violations
@@ -862,8 +1229,22 @@ function validateRefTargetsExist() {
       warnings.push(`req "${name}" links to ADR "${adrRef}" which does not exist`)
     }
     const roadmapRef = extractRefPath(content, 'Roadmap')
-    if (roadmapRef && !referenceExists(roadmapRef)) {
-      warnings.push(`req "${name}" links to Roadmap "${roadmapRef}" which does not exist`)
+    if (roadmapRef) {
+      const { resolved, stale } = resolveRoadmapRefStatus(cfg, roadmapRef)
+      if (resolved.length === 0) {
+        warnings.push(`req "${name}" links to Roadmap "${roadmapRef}" which does not exist`)
+      } else if (resolved.length === 1) {
+        if (stale) {
+          // literal falhou, resolvido só pelo fallback de basename num outro estado: o
+          // vínculo aponta para um caminho de estado velho — o serve casa edge.To pelo
+          // literal e desenharia aresta órfã para o mesmo vínculo se calássemos aqui.
+          const actualState = path.basename(path.dirname(resolved[0]))
+          warnings.push(`req "${name}" links to Roadmap "${roadmapRef}" but the file is now in ${actualState}/ (stale state path)`)
+        }
+        // senão: resolvido pelo caminho literal — nenhum aviso.
+      } else {
+        warnings.push(`req "${name}" links to Roadmap "${roadmapRef}" is ambiguous: found in multiple states: ${resolved.join(', ')}`)
+      }
     }
   }
 
@@ -876,21 +1257,90 @@ function referenceExists(ref) {
   return false
 }
 
+// isStaleRoadmapStateRef reporta se `ref` (um valor de campo Roadmap: já extraído) parece ter sido
+// gravado com uma pasta de estado que pode ter ficado velha — condição de entrada do fallback por
+// basename (resolveRoadmapRefByBasename). Ver o comentário completo em
+// internal/validator/validator.go, isStaleRoadmapStateRef (fonte canônica, ROADMAP-2026-09-05, ML-3B).
+function isStaleRoadmapStateRef(ref) {
+  const parent = path.basename(path.dirname(ref.replace(/\\/g, '/')))
+  return AGENT_NAMESPACE_STATE_NAMES.has(parent)
+}
+
+// resolveRoadmapRefByBasename procura, nos diretórios de ESTADO do roadmap_dir (backlog/analyzing/
+// wip/blocked/done/abandoned, honrando roadmap_namespacing), um arquivo cujo basename case com
+// path.basename(ref). Escopo restrito ao campo Roadmap: — ver a justificativa completa (REQ sem
+// dimensão de estado / ADR de REQ, árvore de ADR flat) no comentário gêmeo em
+// internal/validator/validator.go, resolveRoadmapRefByBasename.
+//
+// Retorna a lista de caminhos absolutos encontrados: 0 (sem match), 1 (resolvido) ou mais de 1
+// (ambíguo — decisão do chamador).
+function resolveRoadmapRefByBasename(cfg, ref) {
+  const base = path.basename(ref)
+  if (base === '' || base === '.' || base === path.sep) return []
+  const found = []
+  const seen = new Set()
+  for (const state of Array.from(AGENT_NAMESPACE_STATE_NAMES).sort()) {
+    for (const stateDir of resolveStateDirs(cfg, state)) {
+      let entries
+      try {
+        entries = fs.readdirSync(stateDir, { withFileTypes: true })
+      } catch {
+        continue
+      }
+      for (const entry of entries) {
+        if (entry.name !== base || entry.isDirectory()) continue
+        const full = path.normalize(path.join(stateDir, entry.name))
+        if (!seen.has(full)) {
+          seen.add(full)
+          found.push(full)
+        }
+      }
+    }
+  }
+  found.sort()
+  return found
+}
+
+// resolveRoadmapRef resolve um valor de campo Roadmap: já extraído: caminho literal primeiro
+// (idêntico a referenceExists — preserva o branch de diretório existente hoje), e só cai para o
+// fallback por basename quando o literal falha e isStaleRoadmapStateRef(ref) indica que vale a
+// pena tentar. Retorna 0 (quebrado), 1 (resolvido) ou >1 (ambíguo) caminhos.
+function resolveRoadmapRef(cfg, ref) {
+  return resolveRoadmapRefStatus(cfg, ref).resolved
+}
+
+// resolveRoadmapRefStatus é resolveRoadmapRef com um flag adicional: stale=true quando a
+// resolução só teve sucesso via resolveRoadmapRefByBasename (o caminho literal falhou e o
+// arquivo foi encontrado em outra pasta de estado). Espelha
+// internal/validator/validator.go:resolveRoadmapRefStatus (fonte canônica, ROADMAP-2026-09-05, ML-3B).
+function resolveRoadmapRefStatus(cfg, ref) {
+  const expandedRef = config.expandPath ? config.expandPath(ref) : ref
+  if (fs.existsSync(expandedRef)) return { resolved: [expandedRef], stale: false }
+  if (!isStaleRoadmapStateRef(ref)) return { resolved: [], stale: false }
+  const found = resolveRoadmapRefByBasename(cfg, ref)
+  return { resolved: found, stale: found.length > 0 }
+}
+
 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 (_) {}
+    const content = readFileForRule('req_roadmap_lifecycle', filePath, warnings)
+    if (content === null) continue
+    if (!reqStatusIsOpen(content)) continue
+    const ref = extractRefPath(content, 'Roadmap')
+    if (!ref) continue
+    const resolved = resolveRoadmapRef(cfg, ref)
+    if (resolved.length !== 1) {
+      // 0 = vínculo quebrado, >1 = ambíguo — ambos já reportados por validateRefTargetsExist.
+      // Esta regra só decide estado quando há UM arquivo real de onde derivá-lo.
+      continue
+    }
+    const expandedRef = resolved[0]
+    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/`)
+    }
   }
   return warnings
 }
@@ -932,12 +1382,7 @@ function validateFolderStatusCoherence() {
 
   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 = [] }
-    }
+    const agents = resolveAgentNamespaces(cfg, cfg.roadmapDir)
     for (const agent of agents) {
       for (const state of states) {
         dirs.push({ dir: path.join(cfg.roadmapDir, agent, state), state })
@@ -957,28 +1402,27 @@ function validateFolderStatusCoherence() {
       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
-        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
-              }
+      const content = readFileForRule('folder_status', path.join(dir, name), warnings)
+      if (content === null) continue
+      // 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 (_) {}
+      }
+      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}"`)
+      }
     }
   }
   return warnings
@@ -992,12 +1436,7 @@ function validateFilenameUniqueness() {
 
   const listErrors = []
   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 agents = resolveAgentNamespaces(cfg, cfg.roadmapDir)
     for (const agent of agents) {
       for (const state of states) {
         const dir = path.join(cfg.roadmapDir, agent, state)
@@ -1132,8 +1571,15 @@ function validateNoteOrphan(cwd) {
 
   const indexPath = path.join(vaultDir, 'index.md')
   let indexContent = ''
-  if (fs.existsSync(indexPath)) {
-    indexContent = fs.readFileSync(indexPath, 'utf8')
+  try {
+    indexContent = readRegularFileSync(indexPath).toString('utf8')
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      // index.md existe mas nao pode ser lido (permissao, FIFO...) -- diagnostica em vez de
+      // tratar como indice vazio, que produziria um "not referenced" falso para toda nota
+      // (ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio, ML-1G).
+      return [inspectionDiagnostic('note_orphan', indexPath, err)]
+    }
   }
 
   const notes = fs.readdirSync(vaultDir).filter((f) => f.endsWith('.md') && f !== 'index.md')
@@ -1205,6 +1651,61 @@ const CREDENTIAL_GUARD_HOOK_FILES = [
 // Qualquer valor que não bata em nenhuma das 3 formas retorna null — o chamador NÃO deve tratar
 // isso como violação. Não é função desta regra adivinhar wiring próprio do usuário fora dos
 // formatos que o trackfw gera.
+// pathIsAnchoredForHookConfig reporta se raw é um caminho ANCORADO para os fins de um comando de
+// hook lido de config de CLI de agente e executado por bash — não se é absoluto para o SO host.
+// Decisão: ADR-2026-09-04-caminho-posix-ancorado-num-config-lido-por-cli-de-agente-e-absoluto-
+// independente-do-so-host. Quem interpreta esse caminho é o bash (ou o próprio CLI de agente),
+// nunca o process.platform do runtime Node — por isso este predicado é a UNIÃO de duas formas,
+// nunca a definição de "absoluto" de um único SO:
+//   - POSIX: prefixo "/" — ancorado em qualquer host, inclusive rodando em Windows via Git Bash.
+//   - Windows: letra de unidade ("C:\..." / "C:/...") ou UNC ("\\servidor\share") — ancorado em
+//     qualquer host, inclusive medido a partir de macOS/Linux (D1 da ADR: uma letra de unidade
+//     também é ancorada, independente de onde o validator roda).
+//
+// 🔴 Requisito duro da ADR: ZERO chamada dependente de SO aqui — nada de path.isAbsolute,
+// path.sep, ou qualquer predicado do módulo "path" que responda com base no process.platform.
+// `path.isAbsolute("/opt/foo")` é `false` no Windows — essa é exatamente a lacuna que motivou
+// esta função. Invariante por construção, verificável por grep.
+//
+// D2 da ADR: este predicado NÃO substitui path.isAbsolute nos sítios de travessia real de
+// sistema de arquivos (ex.: linha 95 e npm/src/integrations/manager.js) — ali o SO É a
+// autoridade certa. Uso restrito aos sítios de classificação de config de hook.
+function pathIsAnchoredForHookConfig(raw) {
+  if (!raw) return false
+  if (raw[0] === '/') return true
+  // UNC: \\servidor\share\... — exige um segmento de SERVIDOR não vazio e diferente de "." ou
+  // ".." (não são hostname válido), seguido de um separador, seguido de um segmento de SHARE não
+  // vazio que não comece com outra barra invertida (evita componente vazio quando há barra dupla
+  // no meio). "\\" e "\\x" sozinhos (sem separador de share), "\\.\x" / "\\..\evil" (server "."
+  // ou ".."), e "\\..\\evil" (barra dupla no meio produz share vazio) NÃO são UNC válido — são
+  // POSIX cwd-dependent (barra invertida não é separador em POSIX), e aceitá-los como ancorado
+  // seria o afrouxamento inverso que este predicado existe para evitar (ressalva do parecer
+  // hades-tf de 2026-09-04 sobre o ML-3A; a notação exata do exemplo "\\..\\evil" no parecer é
+  // ambígua entre 1 e 2 barras antes de "evil" — a checagem de server !== "."/".." fecha as duas
+  // leituras, não só uma). A forma POSIX equivalente, "//servidor/share", já é coberta pelo braço
+  // raw[0]==='/' acima — este braço cobre só a forma com barra invertida.
+  if (raw.length >= 2 && raw[0] === '\\' && raw[1] === '\\') {
+    const rest = raw.slice(2)
+    const sepIdx = rest.indexOf('\\')
+    if (sepIdx > 0) {
+      const server = rest.slice(0, sepIdx)
+      const share = rest.slice(sepIdx + 1)
+      if (server !== '.' && server !== '..' && share.length > 0 && share[0] !== '\\') return true
+    }
+  }
+  // Letra de unidade: C:\... ou C:/...
+  if (raw.length >= 3 && isASCIIDriveLetter(raw[0]) && raw[1] === ':' && (raw[2] === '\\' || raw[2] === '/')) {
+    return true
+  }
+  return false
+}
+
+// isASCIIDriveLetter reporta se ch é uma letra ASCII (a-z, A-Z) — reconhecimento de letra de
+// unidade do Windows em pathIsAnchoredForHookConfig.
+function isASCIIDriveLetter(ch) {
+  return (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z')
+}
+
 function resolveCredentialGuardHookPath(raw, root) {
   const claudePrefix = '$CLAUDE_PROJECT_DIR/'
   const geminiPrefix = '$GEMINI_PROJECT_DIR/'
@@ -1220,7 +1721,7 @@ function resolveCredentialGuardHookPath(raw, root) {
     const inner = raw.slice(codexPrefix.length, raw.length - 1)
     return path.join(root, inner)
   }
-  if (!raw.startsWith('$') && !raw.startsWith('"') && !path.isAbsolute(raw) && !raw.startsWith('~/')) {
+  if (!raw.startsWith('$') && !raw.startsWith('"') && !pathIsAnchoredForHookConfig(raw) && !raw.startsWith('~/')) {
     // Caminho relativo puro — Cursor (beforeShellExecution/preToolUse), GitHub Copilot CLI
     // (campo "bash"), Kiro (action.command).
     // ~/… é excluído: é classe 1 (tilde expande para $HOME — ancorado) mas o validator não expande
@@ -1263,7 +1764,7 @@ function classifyHookAnchorage(rawStripped, wasQuoted) {
     rawStripped.startsWith('$CLAUDE_PROJECT_DIR/') ||
     rawStripped.startsWith('$GEMINI_PROJECT_DIR/') ||
     rawStripped.startsWith('$(git rev-parse --show-toplevel)/') ||
-    path.isAbsolute(rawStripped)
+    pathIsAnchoredForHookConfig(rawStripped)
   ) {
     return HOOK_ANCHORAGE_CLASS_ANCHORED
   }
@@ -1279,7 +1780,7 @@ function classifyHookAnchorage(rawStripped, wasQuoted) {
     rawStripped.startsWith('${PWD}/') ||
     rawStripped.startsWith('./') ||
     rawStripped.startsWith('../') ||
-    (!rawStripped.startsWith('$') && !path.isAbsolute(rawStripped))
+    (!rawStripped.startsWith('$') && !pathIsAnchoredForHookConfig(rawStripped))
   ) {
     return HOOK_ANCHORAGE_CLASS_CWD_DEPENDENT
   }
@@ -1288,13 +1789,28 @@ function classifyHookAnchorage(rawStripped, wasQuoted) {
 }
 
 // cwdDependentReason retorna o sufixo de mensagem específico por forma para violações de
-// classe 2, iniciando em "with a …". Dois formatos: formas contendo $PWD ou ${PWD} (em qualquer
-// posição, inclusive em wrappers sh -c / env) recebem a mensagem do $PWD; demais recebem
-// "bare relative path". Usa includes (não startsWith) para cobrir sh -c "$PWD/…" e env FOO=x $PWD/….
+// classe 2, iniciando em "with a …". Formatos: formas contendo $PWD ou ${PWD} (em qualquer
+// posição, inclusive em wrappers sh -c / env) recebem a mensagem do $PWD; "~/…" (D4 da
+// ADR-2026-09-04) recebe "quoted tilde path"; "~usuario/…" recebe "named-user tilde path";
+// demais recebem "bare relative path". Usa includes (não startsWith) para cobrir
+// sh -c "$PWD/…" e env FOO=x $PWD/….
+//
+// 🔴 D4 da ADR-2026-09-04: achado do ML-2B — "~usuario/" e "\"~/\"" caíam no catch-all e
+// recebiam "bare relative path", que não é o motivo real: ~user/ EXPANDE em POSIX (indecidível
+// sem executar shell, não relativo), e "~/" só falha por causa das ASPAS. O invariante que
+// permite reconhecer "~/" aqui sem receber wasQuoted como parâmetro: classifyHookAnchorage já
+// classifica "~/…" SEM aspas como classe 1 (ancorado) — logo todo "~/…" que chega aqui (classe
+// 2) só pode ter vindo de um valor originalmente citado; ver stripOuterQuotesForClassify.
 function cwdDependentReason(rawStripped) {
   if (rawStripped.includes('$PWD') || rawStripped.includes('${PWD}')) {
     return 'with a $PWD path — $PWD expands to the current working directory, not the project root; run `trackfw update` to fix it'
   }
+  if (rawStripped.startsWith('~/')) {
+    return 'with a quoted tilde path — double quotes prevent shell tilde expansion, so this never resolves to $HOME; run `trackfw update` to fix it'
+  }
+  if (rawStripped.startsWith('~')) {
+    return "with a named-user tilde path — ~user/ expands to that user's home directory, not the project root, and this validator cannot resolve it without running a shell; run `trackfw update` to fix it"
+  }
   return "with a bare relative path — this command only resolves from the project root and will silently fail when the agent's cwd is a subdirectory; run `trackfw update` to fix it"
 }
 
@@ -1364,31 +1880,96 @@ function collectCredentialGuardCommands(value, out) {
 //   - A regra só avalia entradas que EXISTEM. Ausência de entrada de guard é estado legítimo
 //     (guard global instalado via `trackfw update harness`) — nunca é violação por si só.
 //   - Arquivo de hook ausente é pulado em silêncio.
-//   - Arquivo de hook presente mas com JSON inválido é pulado em silêncio — validar a forma do
-//     JSON não é escopo desta regra.
+//   - ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio, ML-1A:
+//     arquivo de hook presente mas com JSON inválido deixou de ser pulado em silêncio — ver o
+//     bloco catch do JSON.parse abaixo para a decisão e a medição que a sustentam.
 //
 // process.cwd() no Node já retorna o caminho FÍSICO (resolve symlinks via getcwd(3) diretamente),
 // diferente de os.Getwd() do Go — ver o comentário sobre EvalSymlinks em
 // internal/validator/validator_git_branch_guard.go's validateGuardHookResolvable equivalente
 // (validator_credential_guard.go). Nenhuma resolução extra de symlink é necessária aqui.
+// isValidUtf8Buffer reports whether buf decodes losslessly as UTF-8, using a fatal TextDecoder
+// (throws instead of substituting U+FFFD). Used purely to CLASSIFY which message to emit when
+// JSON.parse goes on to fail below — never to gate whether parsing is attempted. buf.toString(
+// 'utf8') (the actual parse input) stays lossy on purpose, mirroring the coercion Go's
+// json.Unmarshal already does on raw bytes — ROADMAP-2026-09-06-...-config-ilegivel-deixa-de-ser-
+// silencio, ML-1B; see validateGuardHookResolvable's JSON.parse catch block for why.
+function isValidUtf8Buffer(buf) {
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(buf)
+    return true
+  } catch (_) {
+    return false
+  }
+}
+
 function validateGuardHookResolvable(scriptMarker, cwd) {
   const root = cwd || process.cwd()
   const msgs = []
 
   for (const hf of CREDENTIAL_GUARD_HOOK_FILES) {
     const fullPath = path.join(root, hf.relPath)
-    let content
+    let raw
     try {
-      content = fs.readFileSync(fullPath, 'utf8')
+      raw = readRegularFileSync(fullPath)
     } catch (e) {
       if (e.code === 'ENOENT') continue
+      // ROADMAP-2026-09-06-...-config-ilegivel-deixa-de-ser-silencio, ML-1C: readRegularFileSync
+      // replaces the bare fs.readFileSync — a FIFO at fullPath made fs.readFileSync block
+      // INDEFINITELY (hades-tf's ML-1B barrier, `mkfifo .claude/settings.json`), which this branch
+      // could never reach because the call never returned. readRegularFileSync's synthetic
+      // 'ENOTFILE' error (never 'ENOENT') falls into this SAME accusing branch below.
+      //
+      // ROADMAP-2026-09-06-...-config-ilegivel-deixa-de-ser-silencio, ML-1B: was an unconditional
+      // `continue` regardless of e.code — a dead `if (e.code === 'ENOENT') continue` above it,
+      // then `continue` again for EVERY other error (EACCES, EISDIR, ELOOP...). hades-tf's ML-1A
+      // barrier reproduced this live (chmod 000, and a directory in place of the file): `trackfw
+      // validate --json` exited 0, no violation, no mention of the file — success reported about
+      // wiring the rule never actually inspected, the exact defect this ML exists to close, for a
+      // different `continue` than the JSON-parse one ML-1A already fixed. Same remedy as the
+      // invalid-JSON branch below.
+      msgs.push(
+        `${hf.relPath} (${hf.cli}) could not be read — trackfw cannot tell whether ${scriptMarker} is ` +
+        `wired here, and ${hf.cli} cannot load any hook from a file it cannot read; fix the file, or run ` +
+        '`trackfw update` to regenerate it'
+      )
       continue
     }
 
+    // ML-1B: content is the SAME lossy decode this function has always used (invalid bytes become
+    // U+FFFD, never throws) — wasValidUtf8 only classifies which message to emit if JSON.parse
+    // fails below; it never changes whether parsing is attempted.
+    const wasValidUtf8 = isValidUtf8Buffer(raw)
+    const content = raw.toString('utf8')
+
     let parsed
     try {
       parsed = JSON.parse(content)
     } catch (_) {
+      // ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio,
+      // ML-1A: was a silent `continue` (fail-open) — port of Go's validateGuardHookResolvable
+      // (internal/validator/validator_credential_guard.go) — see that function's json.Unmarshal
+      // error branch for the full decision and measurement. CREDENTIAL_GUARD_HOOK_FILES is a
+      // closed, enumerable list (6 entries) trackfw itself owns/merges into; invalid JSON in any
+      // of them is never a legitimate state, since hf.cli itself requires strict JSON to load its
+      // own hooks from that file.
+      //
+      // ML-1B: not-valid-UTF-8 gets its own message (D4 of ADR-2026-09-04 — classify right,
+      // explain right, or the reader investigates the wrong thing; e.g. a file saved as UTF-16
+      // looks fine in the user's editor).
+      if (!wasValidUtf8) {
+        msgs.push(
+          `${hf.relPath} (${hf.cli}) is not valid UTF-8 — trackfw cannot tell whether ${scriptMarker} is ` +
+          `wired here, and ${hf.cli} cannot load any hook from a file it cannot decode; fix the file's ` +
+          'encoding, or run `trackfw update` to regenerate it'
+        )
+        continue
+      }
+      msgs.push(
+        `${hf.relPath} (${hf.cli}) is not valid JSON — trackfw cannot tell whether ${scriptMarker} is ` +
+        `wired here, and ${hf.cli} cannot load any hook from a file it cannot parse; fix the file, or run ` +
+        '`trackfw update` to regenerate it'
+      )
       continue
     }
 
@@ -1435,7 +2016,7 @@ function validateGuardHookResolvable(scriptMarker, cwd) {
 
       if (!stat) {
         msgs.push(`${hf.relPath} (${hf.cli}) references ${scriptMarker} resolved to "${resolved}", but the script does not exist — run \`trackfw update\` to regenerate it`)
-      } else if ((stat.mode & 0o111) === 0) {
+      } else if (_platform !== 'win32' && (stat.mode & 0o111) === 0) {
         msgs.push(`${hf.relPath} (${hf.cli}) references ${scriptMarker} resolved to "${resolved}", but the script is not executable — run \`trackfw update\` to regenerate it`)
       }
     }
@@ -1644,10 +2225,29 @@ function validateCredentialGuardScriptIntegrity(cwd) {
   const relPath = 'scripts/trackfw-credential-guard.sh'
   let content
   try {
-    content = fs.readFileSync(path.join(root, relPath), 'utf8')
+    // ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio, ML-1C:
+    // readRegularFileSync (defined above) replaces the bare fs.readFileSync — a FIFO at this path
+    // made fs.readFileSync block INDEFINITELY (hades-tf's ML-1B barrier), a hang this catch block
+    // could never reach because the read never returned. The non-ENOENT accusing branch below
+    // (already correct pre-ML-1C, unlike its Go/Python siblings) needed no change for this fix.
+    content = readRegularFileSync(path.join(root, relPath)).toString('utf8')
   } catch (e) {
     if (e.code === 'ENOENT') return []
-    return [inspectionDiagnostic('credential_guard_script_integrity', relPath, e)]
+    // ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio, ML-1C:
+    // was `[inspectionDiagnostic(...)]` — correct in SUBSTANCE before this ML (already a
+    // violation, not a silence, unlike Go which aborted and Python which silenced), but its
+    // 'rule: could not inspect "target": cause' shape put this runtime's message text out of
+    // parity with Go/Python's "could not be read" phrasing FOR THIS SPECIFIC RULE FAMILY once all
+    // 3 runtimes actually produce a message here — a divergence that had no observable effect
+    // before ML-1C (Go/Python never reached this branch at all), but would become a real 3-CLI
+    // text mismatch the moment all 3 runtimes accuse on the same fixture. Unified to the same
+    // fixed text validateGuardHookResolvable / validateGuardGlobalScriptIntegrity already use,
+    // matching Go's identical fix in validateCredentialGuardScriptIntegrity
+    // (validator_credential_guard_integrity.go).
+    return [
+      `${relPath} could not be read — trackfw cannot tell whether this script matches the ` +
+      'template it should; fix the file, or run `trackfw update` to regenerate it',
+    ]
   }
 
   if (content === CREDENTIAL_GUARD_SCRIPT_REFERENCE) return []
@@ -1716,12 +2316,31 @@ set -f
 # --- 0. Drena o stdin ANTES de qualquer saída antecipada (ML-1B, ROADMAP-2026-08-17-guard-
 # global-cabeado-com-no-op-fora-de-projeto-e-integridade-independente-de-fiacao.md): sem isso,
 # quem escreve o payload JSON no pipe recebe EPIPE quando o no-op abaixo sai com 0 antes de ler
-# — reprodutível em 100% das chamadas fora de projeto trackfw, não é corrida de timing. Só drena
-# se stdin não for um terminal interativo (-t 0): em invocação manual sem pipe, "cat" bloquearia
-# esperando EOF (Ctrl-D). O valor lido é reaproveitado no passo 1 abaixo — nunca há uma segunda
-# leitura.
+# — reprodutível em 100% das chamadas fora de projeto trackfw, não é corrida de timing. O dreno
+# roda incondicionalmente, com orçamento de tempo (ML-3A, ver abaixo). O valor lido é reaproveitado no passo 1 abaixo — nunca há uma segunda leitura.
+#
+# ML-3A (ROADMAP-2026-09-09-guard-emite-hookspecificoutput-e-a-razao-chega-ao-modelo-nos-3-
+# clis.md): o discriminante que existia aqui era "-t 0" -- separa "terminal interativo" de
+# "pipe", não "vai receber EOF" de "não vai". Qualquer chamador não-tty que segure stdin aberta
+# (ex.: um runtime de hook que nunca fecha o descritor) travava o antigo "cat" para sempre, sem
+# limite -- foi o que pendurou "make quality" por 1h05 quando o gate de schema (ML-2A) chamou o
+# guard sem "</dev/null" em 3 sítios. Substituído por dreno com ORÇAMENTO DE TEMPO via
+# "read -t <segundos> -d ''": builtin do próprio bash desde a 3.0 (não do coreutils) -- medido
+# idêntico no bash 3.2 (padrão do macOS) e no bash 5.3 (Linux/Homebrew); o bash do MSYS2/Git-Bash
+# do Windows é bash de verdade e traz o mesmo builtin. Evita depender de "timeout(1)", que NÃO
+# existe no macOS base nem no MSYS2 mínimo. "-d ''" faz o read tentar ler até o EOF real (NUL
+# nunca aparece em payload de hook); "-t" interrompe a espera no orçamento e, medido contra um
+# FIFO nunca fechado (bash 3.2 e 5.3), preserva na variável qualquer prefixo já lido antes do
+# timeout -- sem perda do que chegou, só do que nunca chegou. 2s de orçamento: folga generosa
+# para o payload pequeno de um hook sob scheduler sob carga (CI, "make quality" paralelo), e
+# ainda curto o bastante para o travamento continuar perceptível em vez de indefinido. Estourar
+# o orçamento NÃO libera o bloqueio: o passo 1 abaixo já prefere "$*" quando há argumento
+# posicional, e cai para o que foi lido até o limite quando não há -- "exit 2" e o fail-closed
+# continuam idênticos nos dois casos. O antigo desvio para invocação manual em terminal (skip
+# total quando "-t 0") foi removido de propósito: era o próprio discriminante errado que este ML
+# elimina, não um caso a preservar -- agora toda invocação drena com o mesmo orçamento de 2s.
 _TRACKFW_STDIN=""
-[ -t 0 ] || _TRACKFW_STDIN=$(cat 2>/dev/null || true)
+IFS= read -r -t 2 -d '' _TRACKFW_STDIN || true
 
 # --- 0b. No-op fora de projeto trackfw (ADR-2026-08-17-guard-global-cabeado-com-no-op-fora-de-
 # projeto-trackfw.md): sobe diretórios a partir do cwd FÍSICO (pwd -P, resolve symlink) até
@@ -2251,7 +2870,7 @@ case "$SUBCOMMAND" in
     ;;
 esac
 
-printf '{"decision":"block","reason":"%s"}\\n' "$REASON"
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\\n' "$REASON"
 echo "$REASON" >&2
 exit 2
 `
@@ -2265,10 +2884,19 @@ function validateGitBranchGuardScriptIntegrity(cwd) {
   const relPath = 'scripts/trackfw-git-branch-guard.sh'
   let content
   try {
-    content = fs.readFileSync(path.join(root, relPath), 'utf8')
+    // ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio, ML-1C:
+    // same readRegularFileSync substitution as validateCredentialGuardScriptIntegrity's identical
+    // comment above — closes the FIFO hang; the accusing branch below needed no change.
+    content = readRegularFileSync(path.join(root, relPath)).toString('utf8')
   } catch (e) {
     if (e.code === 'ENOENT') return []
-    return [inspectionDiagnostic('git_branch_guard_script_integrity', relPath, e)]
+    // ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio, ML-1C:
+    // same message unification as validateCredentialGuardScriptIntegrity's identical comment
+    // above — text parity with Go/Python for this rule family.
+    return [
+      `${relPath} could not be read — trackfw cannot tell whether this script matches the ` +
+      'template it should; fix the file, or run `trackfw update` to regenerate it',
+    ]
   }
 
   if (content === GIT_BRANCH_GUARD_SCRIPT_REFERENCE) return []
@@ -2486,28 +3114,68 @@ function globalGuardConfigPath(gf, scriptMarker) {
 // prefix-stripping is needed here: any matched command that is NOT already an absolute path is
 // skipped (never treated as a violation).
 //
-// Fail-open: unresolvable $HOME, unreadable file, or invalid JSON all skip that file in silence —
-// same contract validateGuardHookResolvable already has for project-scope files.
+// Fail-open: unresolvable $HOME and unreadable file skip that file in silence — legitimate states.
+// Invalid JSON no longer does — see ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-
+// deixa-de-ser-silencio, ML-1A, and the JSON.parse catch block below for the decision and measurement.
 function validateGuardGlobalHookResolvable(scriptMarker) {
-  const home = os.homedir()
+  const home = homedir()
   if (!home) return []
 
   const msgs = []
   for (const gf of GLOBAL_GUARD_CONFIG_FILES) {
     const relPath = globalGuardConfigPath(gf, scriptMarker)
     const fullPath = path.join(home, relPath)
-    let content
+    let raw
     try {
-      content = fs.readFileSync(fullPath, 'utf8')
+      raw = readRegularFileSync(fullPath)
     } catch (e) {
       if (e.code === 'ENOENT') continue
+      // ROADMAP-2026-09-06-...-config-ilegivel-deixa-de-ser-silencio, ML-1C: same
+      // readRegularFileSync substitution as the project-scope sibling — see that function's
+      // identical comment for the FIFO hang this closes.
+      //
+      // ROADMAP-2026-09-06-...-config-ilegivel-deixa-de-ser-silencio, ML-1B: same decision as the
+      // project-scope sibling (validateGuardHookResolvable, above) — was an unconditional
+      // `continue` for every non-ENOENT read error. See that function's read-error catch branch
+      // for the full measurement (hades-tf ML-1A barrier, reproduced live).
+      msgs.push(
+        `~/${relPath} (${gf.cli}, global scope) could not be read — trackfw cannot tell whether ${scriptMarker} is ` +
+        `wired here, and ${gf.cli} cannot load any hook from a file it cannot read; fix the file, or run ` +
+        '`trackfw update harness` to regenerate it'
+      )
       continue
     }
 
+    // ML-1B: see validateGuardHookResolvable's identical comment above for why decoding, not just
+    // parsing, must be classified separately here.
+    const wasValidUtf8 = isValidUtf8Buffer(raw)
+    const content = raw.toString('utf8')
+
     let parsed
     try {
       parsed = JSON.parse(content)
     } catch (_) {
+      // ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio,
+      // ML-1A: same decision as the project-scope sibling (validateGuardHookResolvable, above) —
+      // see that function's json.parse error branch for the full measurement. Applies identically
+      // here: GLOBAL_GUARD_CONFIG_FILES is the same kind of closed, enumerable list (6 entries),
+      // each owned/consumed by gf.cli itself, so invalid JSON is never a legitimate state.
+      //
+      // ML-1B: not-valid-UTF-8 gets its own message — see validateGuardHookResolvable's identical
+      // branch above for the reasoning.
+      if (!wasValidUtf8) {
+        msgs.push(
+          `~/${relPath} (${gf.cli}, global scope) is not valid UTF-8 — trackfw cannot tell whether ${scriptMarker} is ` +
+          `wired here, and ${gf.cli} cannot load any hook from a file it cannot decode; fix the file's ` +
+          'encoding, or run `trackfw update harness` to regenerate it'
+        )
+        continue
+      }
+      msgs.push(
+        `~/${relPath} (${gf.cli}, global scope) is not valid JSON — trackfw cannot tell whether ${scriptMarker} is ` +
+        `wired here, and ${gf.cli} cannot load any hook from a file it cannot parse; fix the file, or run ` +
+        '`trackfw update harness` to regenerate it'
+      )
       continue
     }
 
@@ -2520,7 +3188,10 @@ function validateGuardGlobalHookResolvable(scriptMarker) {
       if (seen.has(seenKey)) continue
       seen.add(seenKey)
 
-      if (!path.isAbsolute(m.raw)) continue
+      // ADR-2026-09-04-caminho-posix-ancorado-...: pathIsAnchoredForHookConfig classifica por
+      // ancoragem (POSIX "/", letra de unidade, UNC), NÃO por path.isAbsolute — que no Windows
+      // devolve false para "/opt/foo/guard.sh" e faria este `continue` pular a entrada inteira.
+      if (!pathIsAnchoredForHookConfig(m.raw)) continue
 
       // ROADMAP-2026-08-17 ML-4B: reproduced by hades-tf (ML-4A barrier) — a global config entry
       // with the correct absolute command but missing/wrong "type" (hand-edited, an older trackfw
@@ -2541,7 +3212,7 @@ function validateGuardGlobalHookResolvable(scriptMarker) {
 
       if (!stat) {
         msgs.push(`~/${relPath} (${gf.cli}, global scope) references ${scriptMarker} resolved to "${m.raw}", but the script does not exist — run \`trackfw update harness\` to regenerate it`)
-      } else if ((stat.mode & 0o111) === 0) {
+      } else if (_platform !== 'win32' && (stat.mode & 0o111) === 0) {
         msgs.push(`~/${relPath} (${gf.cli}, global scope) references ${scriptMarker} resolved to "${m.raw}", but the script is not executable — run \`trackfw update harness\` to regenerate it`)
       }
     }
@@ -2574,17 +3245,33 @@ function validateGuardGlobalHookResolvable(scriptMarker) {
 // scriptMarker doubles as the script's own filename (trackfw-credential-guard.sh /
 // trackfw-git-branch-guard.sh) in both call sites below — same equivalence the Go port relies on.
 function validateGuardGlobalScriptIntegrity(scriptFileName, referenceContent) {
-  const home = os.homedir()
+  const home = homedir()
   if (!home) return []
 
   const scriptPath = path.join(home, '.trackfw', 'scripts', scriptFileName)
   let content
   try {
-    content = fs.readFileSync(scriptPath, 'utf8')
-  } catch (_) {
-    // Not installed is not a violation — same contract as every other *_script_integrity check
-    // (project-scope and global) in this file.
-    return []
+    // ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio, ML-1C:
+    // readRegularFileSync also closes the FIFO hang for this path (see its doc comment above).
+    content = readRegularFileSync(scriptPath).toString('utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      // Not installed is not a violation — same contract as every other *_script_integrity check
+      // (project-scope and global) in this file.
+      return []
+    }
+    // ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio, ML-1C:
+    // was an UNCONDITIONAL `return []` on ANY read error (bare `catch (_)`) — hades-tf's ML-1B
+    // barrier found this silenced EACCES/EISDIR/ELOOP exactly like the pre-ML-1B config-file
+    // `continue` did (fail-open: validate reports health about an artifact it never actually
+    // inspected). Distinguished from absence by e.code, mirroring every other read-error branch in
+    // this file. Message shape mirrors Go's validateGuardGlobalScriptIntegrity — not
+    // inspectionDiagnostic's shape, since this function serves both credential-guard and
+    // git-branch-guard callers and has no rule name of its own to embed.
+    return [
+      `${scriptPath} (global scope) could not be read — trackfw cannot tell whether this script ` +
+      'matches the template it should; fix the file, or run `trackfw update harness` to regenerate it',
+    ]
   }
 
   if (content === referenceContent) return []
@@ -2686,10 +3373,15 @@ function validateCredentialGuardModeDowngrade(cwd) {
 
   let diskContent
   try {
-    diskContent = fs.readFileSync(path.join(root, 'trackfw.yaml'), 'utf8')
+    diskContent = readRegularFileSync(path.join(root, 'trackfw.yaml')).toString('utf8')
   } catch (e) {
     if (e.code === 'ENOENT') return [credentialGuardModeDowngradeMessage()]
-    return [inspectionDiagnostic('credential_guard_mode_downgrade', 'trackfw.yaml', e)]
+    // Fixed-text message, NOT inspectionDiagnostic — e.message (e.g. "EACCES: permission denied,
+    // open 'trackfw.yaml'") diverges from Go's %v and Python's str(e) for the exact same failure;
+    // every sibling "could not be read" message in this guard family avoids raw OS error text for
+    // the same reason (ROADMAP-2026-09-06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-
+    // silencio, ML-1G).
+    return [credentialGuardModeDowngradeReadFailureMessage()]
   }
 
   const diskMode = extractCredentialGuardMode(diskContent)
@@ -2704,6 +3396,13 @@ function credentialGuardModeDowngradeMessage() {
     'otherwise investigate before treating the credential guard as active'
 }
 
+// Fixed-text remedy for a non-ENOENT read failure on trackfw.yaml when HEAD had mode: block — see
+// its call site for why this avoids inspectionDiagnostic's raw OS error text.
+function credentialGuardModeDowngradeReadFailureMessage() {
+  return 'trackfw.yaml could not be read — trackfw cannot tell whether credential_guard.mode ' +
+    'is still block; fix the file, or run `trackfw update` to regenerate it'
+}
+
 // _itemMeta: mapa de message → { rule, file } para enriquecer saída JSON.
 // Populado em applyRule e nos pushs diretos do validateUnfiltered.
 // Permanece em memória apenas durante a execução de uma chamada validate*.
@@ -2740,6 +3439,11 @@ const RULE_DEFAULTS = {
   // git_branch_guard_hook_resolvable is deliberately absent from this map (falls through to
   // 'error'), mirroring credential_guard_hook_resolvable.
   git_branch_guard_script_integrity: 'warning',
+  // ML-4A (REQ-2026-08-29, achado 1 do parecer hades-tf 2026-08-30): namespace oculto/ambíguo (nome
+  // iniciado por ".") é sinal de baixo ruído por natureza, não um defeito de configuração como
+  // agent_namespace_undeclared ('error'). Nunca 'off' por default — silêncio total é o defeito que
+  // esta REQ existe para fechar.
+  agent_namespace_hidden: 'warning',
 }
 
 // ROADMAP-2026-08-12-ancorar-rules-no-head-para-as-regras-de-credential-guard, ML-1A.
@@ -2841,7 +3545,7 @@ const BASELINE_FILE = '.trackfw-baseline.json'
 // Retorna null se o arquivo não existir.
 function loadBaseline() {
   try {
-    const data = fs.readFileSync(BASELINE_FILE, 'utf8')
+    const data = readRegularFileSync(BASELINE_FILE).toString('utf8')
     return JSON.parse(data)
   } catch (e) {
     if (e.code === 'ENOENT') return null
@@ -2898,11 +3602,16 @@ function validateThirdPartyArtifactHasProvenance(cwd) {
   const manifestPath = path.join(root, '.trackfw', 'integrations-manifest.json')
   let manifest
   try {
-    const raw = fs.readFileSync(manifestPath, 'utf8')
+    const raw = readRegularFileSync(manifestPath).toString('utf8')
     manifest = JSON.parse(raw)
   } catch (err) {
     if (err.code === 'ENOENT') return []
-    throw new Error(`thirdparty_artifact_has_provenance: read ${manifestPath}: ${err.message}`)
+    // Used to `throw` here — an unreadable/corrupt manifest crashed the whole `trackfw validate`
+    // process instead of reporting a diagnostic for this one rule and letting every other rule
+    // still run. Same defect class ML-1C fixed for *_script_integrity, found here by measurement
+    // outside the guard family, in parity with the Go fix at the same call site (ROADMAP-2026-09-
+    // 06-fecha-o-fail-open-do-guard-config-ilegivel-deixa-de-ser-silencio, ML-1G).
+    return [inspectionDiagnostic('thirdparty_artifact_has_provenance', manifestPath, err)]
   }
 
   const destinations = []
@@ -2933,7 +3642,18 @@ function validateThirdPartyArtifactHasProvenance(cwd) {
     // instead, which this rule intentionally never reads). path.relative
     // inverts resolve()'s path.resolve(root, relative) exactly. Mirrors
     // internal/validator/validator_thirdparty_provenance.go.
-    const provenanceKey = path.relative(root, destination)
+    //
+    // ML-2A (ADR-2026-09-04, D1 categoria 2 — "chave de dicionario ou identificador"):
+    // path.relative devolve separador NATIVO, e a chave gravada em
+    // thirdparty-provenance.json e sempre "/" (resolveThirdPartySkillDestination monta
+    // o destino por concatenacao explicita com "/", nos 3 runtimes). Sem normalizar, no
+    // Windows a chave nunca casa e TODO artefato de terceiro e reportado como sem
+    // entrada — falso positivo em massa. Go (validator_thirdparty_provenance.go:160) e
+    // Python (validator.py:3530) ja normalizavam; o Node era a divergencia (D4).
+    //
+    // 🔴 So a CHAVE DERIVADA e normalizada. `destination` continua cru e e o que aparece
+    // nas mensagens e no manifest; nada aqui altera caminho passado a syscall (ADR D2).
+    const provenanceKey = normalizeRefSeparator(path.relative(root, destination))
     const entry = (prov.entries || {})[provenanceKey]
     if (!entry) {
       msgs.push(
@@ -2946,7 +3666,7 @@ function validateThirdPartyArtifactHasProvenance(cwd) {
 
     let installed
     try {
-      installed = fs.readFileSync(destination)
+      installed = readRegularFileSync(destination)
     } catch (err) {
       msgs.push(
         `thirdparty_artifact_has_provenance: "${destination}" is claimed as a third-party artifact with an ` +
@@ -3027,6 +3747,15 @@ async function validateUnfiltered() {
 
   // Verificação bidirecional de trace ID (somente se traceIdField configurado)
   const cfg = config.load()
+
+  // ML-2A (REQ-2026-08-29): namespace de agente em disco e não declarado em agents: — violação, não
+  // aviso (ver comentário em validateAgentNamespaceUndeclared).
+  applyRule('agent_namespace_undeclared', validateAgentNamespaceUndeclared(cfg), violations, warnings)
+
+  // ML-4A (achado 1, hades-tf 2026-08-30): contraponto de baixo ruído para nomes ocultos/ambíguos
+  // (iniciados por ".") — aviso, nunca silêncio total, nunca erro (RULE_DEFAULTS abaixo).
+  applyRule('agent_namespace_hidden', hiddenNamespaceWarnings(cfg), violations, warnings)
+
   if (cfg.traceIdField) {
     for (const msg of checkTraceIds(cfg.reqDir, cfg.roadmapDir, cfg.traceIdField)) {
       // O prefixo da mensagem traceid já carrega o nome da regra (ex: "traceid_orphan_roadmap: ...")
@@ -3090,16 +3819,18 @@ function buildInventorySection(cfg) {
   let reqOpen = 0
   let reqDone = 0
   let reqClosed = 0
+  let reqOther = 0
   for (const filePath of reqFiles) {
     let content
     try {
-      content = fs.readFileSync(filePath, 'utf8')
+      content = readRegularFileSync(filePath).toString('utf8')
     } catch (_) {
       continue
     }
     if (reqStatusEquals(content, 'open')) reqOpen++
     else if (reqStatusEquals(content, 'done')) reqDone++
     else if (reqStatusEquals(content, 'closed')) reqClosed++
+    else reqOther++
   }
 
   const roadmapCounts = {}
@@ -3115,7 +3846,14 @@ function buildInventorySection(cfg) {
 
   let section = '\n📊 Inventory\n'
   section += `   ${'ADRs'.padEnd(12)}${adrCount}\n`
-  section += `   ${'REQs'.padEnd(12)}${reqFiles.length}  (${reqOpen} Open · ${reqDone} Done · ${reqClosed} Closed)\n`
+  // Toda grafia fora de open/done/closed cai em reqOther. Sem este bucket o total
+  // bate e a quebra some com a diferenca EM SILENCIO: um acervo com
+  // approved/backlog/abandoned mostra "53 (8 Open · 36 Done · 0 Closed)" sem
+  // indicar que 9 existem e nao estao em lugar nenhum da conta.
+  // O Python ja fazia isto (pypi/trackfw/commands/status.py:58,199).
+  let reqDetail = `${reqOpen} Open · ${reqDone} Done · ${reqClosed} Closed`
+  if (reqOther > 0) reqDetail += ` · ${reqOther} Other`
+  section += `   ${'REQs'.padEnd(12)}${reqFiles.length}  (${reqDetail})\n`
   section += `   ${'Roadmaps'.padEnd(12)}${roadmapTotal}\n`
   section += `     backlog ${roadmapCounts.backlog} · analyzing ${roadmapCounts.analyzing} · wip ${roadmapCounts.wip}\n`
   section += `     blocked ${roadmapCounts.blocked} · done ${roadmapCounts.done} · abandoned ${roadmapCounts.abandoned}\n`
@@ -3129,14 +3867,7 @@ async function getStatus() {
   out += buildInventorySection(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 = [] }
-    }
+    const agents = resolveAgentNamespaces(cfg, cfg.roadmapDir)
     out += '\n⚙ WIP by Agent\n'
     for (const agent of agents) {
       const wip = listDir(cfg.roadmapDir + '/' + agent + '/wip')
@@ -3205,6 +3936,7 @@ async function getStatus() {
 }
 
 module.exports = {
+  _setPlatformForTest,
   validate,
   validateUnfiltered,
   loadBaseline,
@@ -3229,9 +3961,11 @@ module.exports = {
   listDir,
   tryListDir,
   resolveReqFiles,
+  reqWriteDir,
   resolveStateDirs,
   resolveWIPDirs,
   resolveDoneDirs,
+  resolveAgentNamespaces,
   parseSquadFromFrontmatter,
   validateFrontmatterPresence,
   // novas funções ML-1B
@@ -3251,6 +3985,7 @@ module.exports = {
   normalizeBranchSlug,
   // novas funções ML-2B
   contentHasMarker,
+  contentHasMarkerValue,
   ruleSeverity,
   applyRule,
   // novas funções ML-1B (v2.5.1)
@@ -3270,6 +4005,8 @@ module.exports = {
   resolveAdrStatus,
   // ROADMAP-2026-08-12-mitigacao-do-fail-open-do-credential-guard, ML-1A
   resolveCredentialGuardHookPath,
+  // ADR-2026-09-04 (ML-3A): predicado de ancoragem invariante por GOOS
+  pathIsAnchoredForHookConfig,
   // ADR-2026-08-22 (ML-1A): classificação por ancoragem
   HOOK_ANCHORAGE_CLASS_ANCHORED,
   HOOK_ANCHORAGE_CLASS_CWD_DEPENDENT,