trackfw 7.4.0 → 7.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "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/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
 `

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)