trackfw 7.4.0 → 7.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "7.4.0",
+  "version": "7.5.1",
   "description": "Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, Amazon Q, OpenCode, and Kiro.",
   "keywords": [
     "cli",

package/src/commands/update-harness.js

@@ -7,7 +7,7 @@ const identityStore = require('../identity')
 const projectConfig = require('../config')
 const { catalog, buildPlans, IntegrationManager, globalGroupPath } = require('../integrations')
 const { tildeify, validateTargets, buildDocument, humanReport, silenceConsole } = require('../lib/update-engine')
-const { mergeClaudeHookArray, mergeSimpleCommandArray, mergeCopilotHookArray, generateGlobalCredentialGuardScript, generateGlobalGitBranchGuardScript } = require('../generators/hooks')
+const { mergeClaudeHookArray, mergeSimpleCommandArray, mergeCopilotHookArray, GIT_BRANCH_GUARD_SCRIPT, GLOBAL_CREDENTIAL_GUARD_SCRIPT } = require('../generators/hooks')
 const { homedir } = require('../homedir')
 
 // `trackfw update harness` is the global counterpart to `trackfw update` —
@@ -73,6 +73,72 @@ Cadeia: **ADR → REQ → ROADMAP** · Estados: \`backlog / wip / blocked / done
 `
 }
 
+// gitBranchGuardScriptTarget — evaluates (and, unless --dry-run, applies) the
+// global git-branch-guard shell script at
+// ~/.trackfw/scripts/trackfw-git-branch-guard.sh.
+//
+// This target OWNS the script file. It compares content before writing so that
+// an already up-to-date script reports "skipped" and its mtime is left unchanged
+// (REQ-2026-09-09 AC3). Creation does not require --install-missing because
+// ~/.trackfw/scripts/ is 100% trackfw-owned.
+function gitBranchGuardScriptTarget(homeRoot, { dryRun }) {
+  const id = 'git-branch-guard-script'
+  const filePath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-git-branch-guard.sh')
+  const displayPath = tildeify(homeRoot, filePath)
+  const desired = GIT_BRANCH_GUARD_SCRIPT
+
+  try {
+    const exists = fs.existsSync(filePath)
+    const actual = exists ? fs.readFileSync(filePath, 'utf8') : null
+
+    if (exists && actual === desired) {
+      // Content identical — skip write, repair execute bit without touching mtime.
+      try { fs.chmodSync(filePath, 0o755) } catch (_) { /* best-effort */ }
+      return { id, state: 'skipped', path: displayPath }
+    }
+
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, desired, { encoding: 'utf8', mode: 0o755 })
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+// credentialGuardScriptTarget — evaluates (and, unless --dry-run, applies) the
+// global credential-guard shell script at
+// ~/.trackfw/scripts/trackfw-credential-guard.sh.
+//
+// Mirrors gitBranchGuardScriptTarget — same ownership model, same idempotency
+// contract, same absence of --install-missing gate.
+function credentialGuardScriptTarget(homeRoot, { dryRun }) {
+  const id = 'credential-guard-script'
+  const filePath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-credential-guard.sh')
+  const displayPath = tildeify(homeRoot, filePath)
+  const desired = GLOBAL_CREDENTIAL_GUARD_SCRIPT
+
+  try {
+    const exists = fs.existsSync(filePath)
+    const actual = exists ? fs.readFileSync(filePath, 'utf8') : null
+
+    if (exists && actual === desired) {
+      // Content identical — skip write, repair execute bit without touching mtime.
+      try { fs.chmodSync(filePath, 0o755) } catch (_) { /* best-effort */ }
+      return { id, state: 'skipped', path: displayPath }
+    }
+
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, desired, { encoding: 'utf8', mode: 0o755 })
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
 function claudeSkillTarget(homeRoot, { dryRun, installMissing }) {
   const id = 'claude-skill'
   const filePath = path.join(homeRoot, '.claude', 'skills', 'trackfw', 'SKILL.md')
@@ -799,7 +865,10 @@ function catalogBundleTarget(toolId, kind, homeRoot, identityConfig, { dryRun, i
 // which precede claude-agents/claude-skills), with credential-guard always
 // preceding git-branch-guard within a tool — see buildHarnessTargetIDs's
 // comment in update.go for the full rationale.
-const HARNESS_TARGET_IDS = ['claude-skill', 'claude-credential-guard', 'claude-git-branch-guard']
+// Script targets precede every wiring target that references them so that even
+// a --targets-filtered run that only requests a wiring target still finds the
+// script already in place from a prior full run.
+const HARNESS_TARGET_IDS = ['claude-skill', 'git-branch-guard-script', 'credential-guard-script', 'claude-credential-guard', 'claude-git-branch-guard']
 for (const target of catalog.targets) {
   if (target.id === 'codex') HARNESS_TARGET_IDS.push('codex-credential-guard', 'codex-git-branch-guard')
   if (target.id === 'gemini') HARNESS_TARGET_IDS.push('gemini-credential-guard', 'gemini-git-branch-guard')
@@ -818,6 +887,8 @@ function buildHarnessTargets(homeRoot, identityConfig, { dryRun, installMissing
   const include = (id) => !wanted || wanted.includes(id)
   const targets = []
   if (include('claude-skill')) targets.push(claudeSkillTarget(homeRoot, { dryRun, installMissing }))
+  if (include('git-branch-guard-script')) targets.push(gitBranchGuardScriptTarget(homeRoot, { dryRun }))
+  if (include('credential-guard-script')) targets.push(credentialGuardScriptTarget(homeRoot, { dryRun }))
   if (include('claude-credential-guard')) targets.push(credentialGuardTargetClaude(homeRoot, { dryRun, installMissing }))
   if (include('claude-git-branch-guard')) targets.push(gitBranchGuardTargetClaude(homeRoot, { dryRun, installMissing }))
   for (const target of catalog.targets) {
@@ -885,20 +956,11 @@ function run(options) {
   const dryRun = Boolean(options.dryRun)
   const installMissing = Boolean(options.installMissing)
 
-  // The per-CLI *-credential-guard targets below only wire hook entries that
-  // point at ~/.trackfw/scripts/trackfw-credential-guard.sh — none of them
-  // write the script itself (ADR-2026-08-06, decision #2/#3). Without this
-  // call the wiring is installed but every hook invocation fails with
-  // "No such file or directory" because the script never exists.
-  if (!dryRun) {
-    if (options.json) {
-      silenceConsole(() => generateGlobalCredentialGuardScript(homeRoot))
-      silenceConsole(() => generateGlobalGitBranchGuardScript(homeRoot))
-    } else {
-      generateGlobalCredentialGuardScript(homeRoot)
-      generateGlobalGitBranchGuardScript(homeRoot)
-    }
-  }
+  // NOTE: the script files are now first-class targets ("git-branch-guard-script",
+  // "credential-guard-script") positioned before the wiring targets in
+  // HARNESS_TARGET_IDS. The pre-loop unconditional writes that used to live here
+  // have been removed — the target functions handle creation and idempotency.
+  // (REQ-2026-09-09, ML-1A)
 
   // Identidade resolvida do disco antes de buildPlans — pular esta etapa
   // reverteria silenciosamente os nomes customizados para os defaults

package/src/generators/hooks.js

@@ -428,9 +428,12 @@ const GLOBAL_CREDENTIAL_GUARD_SCRIPT = CG_HEADER + CG_DETECTION_CORE + CG_GLOBAL
 // Byte-identical port of internal/generators/scaffold.go:gitBranchGuardScript
 // (Go's canonical reference). Blocks raw `git commit`/`git push`/
 // `git checkout -b` by a subagent, regardless of runtime contract: emits BOTH
-// `{"decision":"block","reason":"..."}` on stdout (Claude/Gemini JSON-stdout
-// style) AND `exit 2` (Codex/Windsurf/Cursor exit-code style) simultaneously,
-// same simplification decision as the Go const's doc comment. Unlike
+// `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":
+// "deny","permissionDecisionReason":"..."}}` on stdout (Claude/Gemini
+// JSON-stdout style — UPDATED 2026-09-09, see the Go const's doc comment for
+// why the previous `{"decision":"block",...}` shape stopped validating) AND
+// `exit 2` (Codex/Windsurf/Cursor exit-code style) simultaneously, same
+// simplification decision as the Go const's doc comment. Unlike
 // CREDENTIAL_GUARD_SCRIPT, this script is IDENTICAL between project and
 // global scope (no trackfw.yaml dependency, no mode/roadmap_dir resolution)
 // — a single constant is written by both generateGitBranchGuardScript and
@@ -495,12 +498,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é
@@ -1030,7 +1052,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
 `
@@ -2387,5 +2409,6 @@ module.exports = {
   SIGNAL_SCRIPT,
   CLEANUP_SCRIPT,
   CREDENTIAL_GUARD_SCRIPT,
+  GLOBAL_CREDENTIAL_GUARD_SCRIPT,
   GIT_BRANCH_GUARD_SCRIPT,
 }

package/src/serve/api_chain.js

@@ -2,7 +2,7 @@
 
 const fs = require('fs')
 const path = require('path')
-const { resolveAgentNamespaces } = require('../validator')
+const { resolveAgentNamespaces, extractRefPath } = require('../validator')
 const { normalizeRefSeparator } = require('../lib/pathfmt')
 
 const ROADMAP_STATES = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
@@ -81,7 +81,7 @@ function collectNodes(dir, type, state) {
     // mesmos operandos: normalizar esta nao pode afeta-la. O caminho de travessia
     // permanece nativo (ADR D2). Espelha internal/serve/api_chain.go:111.
     const id = normalizeRefSeparator(path.join(dir, file))
-    nodes.push({ id, type, title, state, fm })
+    nodes.push({ id, type, title, state, fm, content })
   }
   return nodes
 }
@@ -169,8 +169,21 @@ function handleChain(cfg, req, res) {
 
   function resolveRef(val) {
     if (!val) return null
-    // Tenta pelo nome de arquivo
-    const base = val.replace(/\.md$/, '').toLowerCase().trim()
+    // Tenta pelo nome de arquivo — path.basename(val), não val cru: o formato canônico
+    // gravado por `trackfw req new`/`roadmap new` é o CAMINHO COMPLETO (ADR-2026-08-01), não o
+    // basename isolado. Sem o basename() aqui, um vínculo real como
+    // "docs/roadmaps/wip/ROADMAP-x.md" nunca batia contra a chave "roadmap-x" do fileIndex —
+    // achado do ML-3D: nenhuma aresta REQ/ADR/Roadmap gerada pelo CLI jamais resolvia por este
+    // caminho, mascarado porque os testes existentes só cobrem valor já-basename.
+    //
+    // Por que este arquivo NÃO importa validator.resolveRoadmapRef (ao contrário de
+    // internal/serve/api_chain.go, ML-3D): fileIndex é indexado por basename ACROSS todos os
+    // estados (wip/backlog/blocked/done/abandoned) desde antes desta correção — um vínculo
+    // `roadmap:` "wip/X.md" já resolve contra o node real em "done/X.md" sem fallback extra.
+    // O mecanismo do ML-3B/3D (caminho literal gravado com pasta de estado velha) não afeta
+    // este CLI porque ele nunca comparou por igualdade de caminho completo — só por basename/
+    // título. Ver docs/cli-parity.md, seção "serve: /api/chain".
+    const base = path.basename(val).replace(/\.md$/, '').toLowerCase().trim()
     if (fileIndex.has(base)) return fileIndex.get(base)
     // Tenta pelo título
     const norm = val.toLowerCase().trim()
@@ -202,6 +215,20 @@ function handleChain(cfg, req, res) {
         if (target && target !== id) addEdge(id, target)
       }
     }
+
+    // ML-3D: `trackfw req new` (npm/src/generators/req.js) grava `adr: ""` e `roadmap: ""`
+    // SEMPRE vazios no frontmatter — o valor real vive no corpo, em "## Linked ADR / ADR:
+    // <path>" e "## Linked Roadmap / Roadmap: <path>". O laço de frontmatter acima nunca
+    // encontra esse vínculo para uma REQ gerada pelo próprio CLI (não é caso de borda: é o
+    // formato canônico inteiro). validator.extractRefPath varre o CONTEÚDO inteiro
+    // linha-a-linha (mesma função usada por validateRefTargetsExist) — ponto único de
+    // extração, não duplicado aqui.
+    for (const field of ['req', 'adr', 'roadmap']) {
+      const val = extractRefPath(node.content || '', field)
+      if (!val) continue
+      const target = resolveRef(val)
+      if (target && target !== id) addEdge(id, target)
+    }
   }
 
   // Montar nodes de saída sem o campo fm interno

package/src/validator/index.js

@@ -577,33 +577,65 @@ function contentHasMarker(content, markers) {
   return false
 }
 
-// contentHasMarkerValue retorna true se algum dos markers aparece em content seguido de
-// conteúdo não-branco na mesma linha — isto é, o campo tem um valor real, não apenas o marker.
+// 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: contentHasMarker (acima) detectava "vazio" só pela grafia literal
-// "MARKER + um espaço + \n"/"\r\n" — 5 de 7 grafias naturais de campo vazio escapavam
-// ("MARKER:\n" sem espaço, dois espaços, tab, CRLF sem espaço, três espaços). Esta função
-// decide por VALOR: pega o resto da linha após o marker, descarta \r/\t/espaços das duas
-// pontas, e só considera "tem valor" se sobrar algo. Indiferente a CRLF, tabs e contagem de
-// espaços — cobre as 7 grafias medidas na triagem, não apenas a literal do template.
+// 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 marker of markers) {
-    let start = 0
-    while (true) {
-      const idx = content.indexOf(marker, start)
-      if (idx === -1) break
-      const pos = idx + marker.length
-      let rest = content.slice(pos)
-      const nl = rest.indexOf('\n')
-      if (nl !== -1) rest = rest.slice(0, nl)
-      if (rest.endsWith('\r')) rest = rest.slice(0, -1)
-      if (rest.trim() !== '') return true
-      start = pos
+  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"
@@ -707,7 +739,7 @@ function validateWIPHasREQ() {
       const content = readFileForRule('wip_has_req', path.join(wipDir, name), violations)
       if (content === null) continue
       if (!contentHasMarkerValue(content, cfg.linkFields.req)) {
-        violations.push(`roadmap "${name}" is in wip but has no linked REQ`)
+        violations.push(`roadmap "${name}" is in wip but has no linked REQ (marker must start the line with a real, non-placeholder value)`)
       }
     }
   }
@@ -723,7 +755,7 @@ function validateREQsHaveADR() {
     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`)
+      violations.push(`req "${path.basename(filePath)}" has no linked ADR (marker must start the line with a real, non-placeholder value)`)
     }
   }
   return violations
@@ -739,7 +771,7 @@ function validateBlockedHasREQ() {
       const content = readFileForRule('blocked_has_req', path.join(blockedDir, name), violations)
       if (content === null) continue
       if (!contentHasMarkerValue(content, cfg.linkFields.req)) {
-        violations.push(`roadmap "${name}" is in blocked but has no linked REQ`)
+        violations.push(`roadmap "${name}" is in blocked but has no linked REQ (marker must start the line with a real, non-placeholder value)`)
       }
     }
   }
@@ -755,7 +787,7 @@ function validateREQsHaveRoadmap() {
     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`)
+      violations.push(`req "${path.basename(filePath)}" has no linked Roadmap (marker must start the line with a real, non-placeholder value)`)
     }
   }
   return violations
@@ -1197,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(', ')}`)
+      }
     }
   }
 
@@ -1211,6 +1257,70 @@ 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 = []
@@ -1220,7 +1330,13 @@ function validateREQRoadmapLifecycle() {
     if (!reqStatusIsOpen(content)) continue
     const ref = extractRefPath(content, 'Roadmap')
     if (!ref) continue
-    const expandedRef = config.expandPath ? config.expandPath(ref) : ref
+    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/`)
@@ -2200,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é
@@ -2735,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
 `
@@ -3850,6 +3985,7 @@ module.exports = {
   normalizeBranchSlug,
   // novas funções ML-2B
   contentHasMarker,
+  contentHasMarkerValue,
   ruleSeverity,
   applyRule,
   // novas funções ML-1B (v2.5.1)