trackfw 6.10.0 → 7.1.0

package/src/validator/index.js

@@ -1,10 +1,13 @@
 'use strict'
 
 const fs = require('fs')
+const os = require('os')
 const path = require('path')
+const crypto = require('crypto')
 const { gitOutput } = require('./git-exec')
 const config = require('../config')
 const { checkTraceIds } = require('./traceid')
+const { loadProvenance } = require('../thirdparty/provenance')
 
 const STALE_WIP_DAYS = 7
 let staleWipNowMs = () => Date.now()
@@ -1152,18 +1155,32 @@ function validateNoteOrphan(cwd) {
 // procura dentro dos comandos de hook de projeto.
 const CREDENTIAL_GUARD_SCRIPT_MARKER = 'trackfw-credential-guard.sh'
 
+// GIT_BRANCH_GUARD_SCRIPT_MARKER é o nome do script que a regra git_branch_guard_hook_resolvable
+// procura dentro dos comandos de hook de projeto (ROADMAP-2026-08-15-trackfw-validate-deve-
+// detectar-scripts-de-hook-ausentes-ou-desatualizados, ML-2A — port de
+// internal/validator/validator_git_branch_guard.go's gitBranchGuardScriptMarker). Mesmo padrão de
+// CREDENTIAL_GUARD_SCRIPT_MARKER — só o nome do arquivo muda.
+const GIT_BRANCH_GUARD_SCRIPT_MARKER = 'trackfw-git-branch-guard.sh'
+
 // CREDENTIAL_GUARD_HOOK_FILES é a lista fechada dos arquivos de hook de PROJETO que o trackfw
 // gera hoje e que podem conter uma entrada de credential-guard (ROADMAP-2026-08-12-mitigacao-do
 // -fail-open-do-credential-guard, ML-1A). Hooks de escopo GLOBAL (~/.trackfw/..., trackfw update
 // harness) ficam fora — caso distinto, fora do repositório do usuário, e a checagem de dedup
 // globalCredentialGuardInstalled*() já os pula de propósito nas entradas de projeto.
+//
+// requiresCommandType (ROADMAP-2026-08-17 ML-4B, port of Go's credentialGuardHookFile.
+// requiresCommandType): true for every CLI whose writer always emits a sibling "type":"command"
+// field (Claude/Codex/Gemini, GitHub Copilot CLI, Kiro) — a command match found WITHOUT that
+// sibling is a structurally malformed entry the CLI silently never executes (hades-tf ML-4A
+// barrier finding), not merely "absent". false only for Cursor, whose schema
+// ({"command":...}) never carries a "type" field at all.
 const CREDENTIAL_GUARD_HOOK_FILES = [
-  { relPath: '.claude/settings.json', cli: 'Claude Code' },
-  { relPath: '.codex/hooks.json', cli: 'Codex CLI' },
-  { relPath: '.gemini/settings.json', cli: 'Gemini CLI' },
-  { relPath: '.cursor/hooks.json', cli: 'Cursor' },
-  { relPath: '.github/hooks/trackfw-attention.json', cli: 'GitHub Copilot CLI' },
-  { relPath: '.kiro/hooks/trackfw-attention.json', cli: 'Kiro' },
+  { relPath: '.claude/settings.json', cli: 'Claude Code', requiresCommandType: true },
+  { relPath: '.codex/hooks.json', cli: 'Codex CLI', requiresCommandType: true },
+  { relPath: '.gemini/settings.json', cli: 'Gemini CLI', requiresCommandType: true },
+  { relPath: '.cursor/hooks.json', cli: 'Cursor', requiresCommandType: false },
+  { relPath: '.github/hooks/trackfw-attention.json', cli: 'GitHub Copilot CLI', requiresCommandType: true },
+  { relPath: '.kiro/hooks/trackfw-attention.json', cli: 'Kiro', requiresCommandType: true },
 ]
 
 // resolveCredentialGuardHookPath resolve o valor bruto de um comando de hook (string extraída do
@@ -1203,30 +1220,67 @@ function resolveCredentialGuardHookPath(raw, root) {
   return null
 }
 
-// collectCredentialGuardCommands percorre recursivamente um valor JSON já decodificado e coleta
-// todo valor-string que referencia trackfw-credential-guard.sh, independentemente do nome do
-// campo que o contém.
+// collectCommandsWithMarker percorre recursivamente um valor JSON já decodificado e coleta todo
+// valor-string que contém marker, independentemente do nome do campo que o contém — junto com um
+// sinal estrutural (typeIsCommand) de que o objeto imediato que o contém também tem
+// "type":"command" como campo irmão (ROADMAP-2026-08-17 ML-4B, port de guardCommandMatch em
+// internal/validator/validator_credential_guard.go). Cada entrada de `out` é
+// {raw, typeIsCommand}.
 //
 // Os 6 formatos de hook usam campos diferentes para o comando: "command" (Claude/Codex/
 // Gemini/Cursor), "bash" (GitHub Copilot CLI), "action.command" (Kiro). Varrer por VALOR em vez
-// de por caminho de chave evita acoplar esta regra à forma exata de cada schema.
-function collectCredentialGuardCommands(value, out) {
+// de por caminho de chave evita acoplar esta regra à forma exata de cada schema. Todo schema aqui
+// coloca "type" como IRMÃO do campo do comando dentro do MESMO objeto — nunca aninhado mais fundo
+// — então basta ler "type" do objeto que collectCommandsWithMarker já está visitando; não é
+// necessária uma travessia schema-aware separada.
+//
+// Generalizado (ROADMAP-2026-08-15-trackfw-validate-deve-detectar-scripts-de-hook-ausentes-ou-
+// desatualizados, ML-2A, port de collectCommandsWithMarker em
+// internal/validator/validator_git_branch_guard.go) para aceitar qualquer marker — originalmente
+// collectCredentialGuardCommands, hardcoded para CREDENTIAL_GUARD_SCRIPT_MARKER; reusado agora
+// também para GIT_BRANCH_GUARD_SCRIPT_MARKER, sem duplicar a travessia recursiva.
+function collectCommandsWithMarker(value, marker, out) {
   if (typeof value === 'string') {
-    if (value.includes(CREDENTIAL_GUARD_SCRIPT_MARKER)) out.push(value)
+    // Top-level/loose string match, outside any enclosing object — defensive fallback, not
+    // expected to fire since every hook file read here is rooted at a JSON object. No enclosing
+    // object means no "type" sibling to read.
+    if (value.includes(marker)) out.push({ raw: value, typeIsCommand: false })
     return
   }
   if (Array.isArray(value)) {
-    for (const item of value) collectCredentialGuardCommands(item, out)
+    for (const item of value) collectCommandsWithMarker(item, marker, out)
     return
   }
   if (value && typeof value === 'object') {
-    for (const key of Object.keys(value)) collectCredentialGuardCommands(value[key], out)
+    const typeIsCommand = value.type === 'command'
+    for (const key of Object.keys(value)) {
+      const val = value[key]
+      if (typeof val === 'string') {
+        if (val.includes(marker)) out.push({ raw: val, typeIsCommand })
+        continue
+      }
+      collectCommandsWithMarker(val, marker, out)
+    }
   }
 }
 
-// validateCredentialGuardHookResolvable é a regra "credential_guard_hook_resolvable": para cada
-// arquivo de hook de PROJETO que existir, extrai os comandos que referenciam
-// trackfw-credential-guard.sh, resolve o caminho e verifica que o script existe e é executável.
+// collectCredentialGuardCommands é o wrapper específico de credential-guard sobre
+// collectCommandsWithMarker — preservado para compatibilidade de assinatura (exportada
+// historicamente com 2 argumentos).
+function collectCredentialGuardCommands(value, out) {
+  collectCommandsWithMarker(value, CREDENTIAL_GUARD_SCRIPT_MARKER, out)
+}
+
+// validateGuardHookResolvable é a implementação genérica compartilhada pelas regras
+// "credential_guard_hook_resolvable" e "git_branch_guard_hook_resolvable": para cada arquivo de
+// hook de PROJETO que existir, extrai os comandos que referenciam scriptMarker, resolve o caminho
+// e verifica que o script existe e é executável.
+//
+// Generalizado a partir da antiga validateCredentialGuardHookResolvable (ROADMAP-2026-08-15-
+// trackfw-validate-deve-detectar-scripts-de-hook-ausentes-ou-desatualizados, ML-2A, port de
+// validateGuardHookResolvable em internal/validator/validator_credential_guard.go) — a lógica de
+// resolução de caminho por CLI é idêntica para os 2 scripts, só o marker e o texto da mensagem
+// mudam.
 //
 // Riscos de regressão mapeados no roadmap:
 //   - A regra só avalia entradas que EXISTEM. Ausência de entrada de guard é estado legítimo
@@ -1234,7 +1288,12 @@ function collectCredentialGuardCommands(value, out) {
 //   - 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.
-function validateCredentialGuardHookResolvable(cwd) {
+//
+// 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.
+function validateGuardHookResolvable(scriptMarker, cwd) {
   const root = cwd || process.cwd()
   const msgs = []
 
@@ -1256,16 +1315,27 @@ function validateCredentialGuardHookResolvable(cwd) {
     }
 
     const commands = []
-    collectCredentialGuardCommands(parsed, commands)
+    collectCommandsWithMarker(parsed, scriptMarker, commands)
 
     const seen = new Set()
-    for (const raw of commands) {
-      if (seen.has(raw)) continue
-      seen.add(raw)
+    for (const m of commands) {
+      const seenKey = `${m.raw}${m.typeIsCommand}`
+      if (seen.has(seenKey)) continue
+      seen.add(seenKey)
 
-      const resolved = resolveCredentialGuardHookPath(raw, root)
+      const resolved = resolveCredentialGuardHookPath(m.raw, root)
       if (resolved === null) continue
 
+      // ROADMAP-2026-08-17 ML-4B: a command that resolves to a real path but sits inside a
+      // structurally malformed entry (missing/wrong "type" where this CLI's schema requires it —
+      // hades-tf ML-4A barrier finding) will NEVER be executed by the CLI, regardless of whether
+      // the script itself exists and is executable. Reported instead of the exists/executable
+      // checks below, which assume a structurally valid entry.
+      if (hf.requiresCommandType && !m.typeIsCommand) {
+        msgs.push(`${hf.relPath} (${hf.cli}) references ${scriptMarker} resolved to "${resolved}", but the hook entry is missing "type":"command" (or has an invalid type) — ${hf.cli} will silently never execute it; run \`trackfw update\` to regenerate it`)
+        continue
+      }
+
       let stat = null
       try {
         stat = fs.statSync(resolved)
@@ -1274,9 +1344,9 @@ function validateCredentialGuardHookResolvable(cwd) {
       }
 
       if (!stat) {
-        msgs.push(`${hf.relPath} (${hf.cli}) references trackfw-credential-guard.sh resolved to "${resolved}", but the script does not exist — run \`trackfw update\` to regenerate it`)
+        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) {
-        msgs.push(`${hf.relPath} (${hf.cli}) references trackfw-credential-guard.sh resolved to "${resolved}", but the script is not executable — run \`trackfw update\` to regenerate it`)
+        msgs.push(`${hf.relPath} (${hf.cli}) references ${scriptMarker} resolved to "${resolved}", but the script is not executable — run \`trackfw update\` to regenerate it`)
       }
     }
   }
@@ -1284,6 +1354,18 @@ function validateCredentialGuardHookResolvable(cwd) {
   return msgs
 }
 
+// validateCredentialGuardHookResolvable é a regra "credential_guard_hook_resolvable" — ver
+// validateGuardHookResolvable para a implementação compartilhada.
+function validateCredentialGuardHookResolvable(cwd) {
+  return validateGuardHookResolvable(CREDENTIAL_GUARD_SCRIPT_MARKER, cwd)
+}
+
+// validateGitBranchGuardHookResolvable é a regra "git_branch_guard_hook_resolvable" — ver
+// validateGuardHookResolvable para a implementação compartilhada.
+function validateGitBranchGuardHookResolvable(cwd) {
+  return validateGuardHookResolvable(GIT_BRANCH_GUARD_SCRIPT_MARKER, cwd)
+}
+
 function isGitWorktree(dir) {
   try {
     const out = gitOutput(dir, ['rev-parse', '--is-inside-work-tree'])
@@ -1486,6 +1568,809 @@ function validateCredentialGuardScriptIntegrity(cwd) {
   ]
 }
 
+// ROADMAP-2026-08-15-trackfw-validate-deve-detectar-scripts-de-hook-ausentes-ou-desatualizados,
+// ML-2A: port of internal/validator/validator_git_branch_guard.go — adds git-branch-guard
+// coverage to the two existing credential-guard checks (existence/executability via
+// validateGuardHookResolvable above, and content-drift integrity via
+// validateGitBranchGuardScriptIntegrity below), plus the GLOBAL-scope check that was missing for
+// BOTH guards before this ML (same gap the Go implementation closed first).
+
+// GBG_REF_BACKTICK — validator-local copy of the same escaped-backtick helper hooks.js's
+// GBG_BACKTICK uses (npm/src/generators/hooks.js), to embed REASON's `` `cmd` `` inside the
+// script's double-quoted shell string without breaking this JS template literal.
+const GBG_REF_BACKTICK = '\\`'
+
+// GIT_BRANCH_GUARD_SCRIPT_REFERENCE is a validator-local copy of the
+// scripts/trackfw-git-branch-guard.sh template composed in npm/src/generators/hooks.js
+// (GIT_BRANCH_GUARD_SCRIPT const). Not required directly from generators/hooks.js: like
+// CREDENTIAL_GUARD_SCRIPT_REFERENCE above, generateGitBranchGuardScript() writes to disk AND
+// console.log()s a success line on every call — calling it from inside `trackfw validate` would
+// leak a stray "  ✓ scripts/trackfw-git-branch-guard.sh" line into validate's output. There is no
+// import-cycle constraint in Node (unlike Go's internal/validator ↔ internal/generators cycle —
+// see gitBranchGuardScriptReference's doc comment in
+// internal/validator/validator_git_branch_guard_reference.go) but the console.log side effect is
+// reason enough on its own to keep a local copy here, matching the choice already made for
+// credential-guard in this same file.
+//
+// Unlike CREDENTIAL_GUARD_SCRIPT_REFERENCE, GIT_BRANCH_GUARD_SCRIPT_REFERENCE is used VERBATIM for
+// both the project scope and the global scope (generateGitBranchGuardScript /
+// generateGlobalGitBranchGuardScript write the exact same GIT_BRANCH_GUARD_SCRIPT constant) — so
+// this single reference constant covers both git_branch_guard_script_integrity (project,
+// scripts/trackfw-git-branch-guard.sh) and the global integrity check
+// (~/.trackfw/scripts/trackfw-git-branch-guard.sh), no second reference constant needed.
+//
+// Drift between this copy and the real generator is caught by
+// "GIT_BRANCH_GUARD_SCRIPT_REFERENCE é byte-idêntico ao que generateGitBranchGuardScript emite"
+// (npm/tests/git_branch_guard.test.js): it regenerates the script via generateGitBranchGuardScript
+// into a temp dir and asserts byte-equality against this constant.
+const GIT_BRANCH_GUARD_SCRIPT_REFERENCE = `#!/usr/bin/env bash
+# trackfw git branch guard — bloqueia git commit/push/checkout -b/branch/worktree add -b
+# brutos por subagente
+#
+# TRIPWIRE, NÃO FRONTEIRA DE SEGURANÇA: detecta o caso óbvio — comando git literal, sem
+# indireção de shell — não é defesa contra um agente adversário competente. Evasões que
+# exigem tokenizar como o bash (ex.: git\${IFS}push, {git,push}, g""it push) permanecem
+# abertas por decisão: ver docs/adr/ADR-2026-08-12-nao-ha-prevencao-contra-agente-induzido-
+# com-escrita-irrestrita-a-resposta-e-deteccao-ancorada-no-git.md. O stripping de
+# env/command abaixo reconhece as formas SEM argumentos antes de git (env git ...,
+# command git ...) e o env seguido de uma sequência de atribuições CHAVE=valor
+# (env FOO=bar git ..., env FOO=bar BAZ=qux git ...) — env com FLAGS (env -i git ...,
+# env --ignore-environment git ...) e command com flags (command -p git ...) continuam
+# evadindo; declarado, não fechado (ver AC5 do ML que adicionou esse stripping). A
+# segmentação abaixo
+# (quote_aware_split) evita falso-positivo em texto citado — não deve ser lida como imune a
+# evasão por citação/tokenização do shell.
+set -euo pipefail
+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.
+_TRACKFW_STDIN=""
+[ -t 0 ] || _TRACKFW_STDIN=$(cat 2>/dev/null || 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é
+# achar trackfw.yaml na raiz do projeto. Sem trackfw.yaml em nenhum ancestral, o guard não se
+# aplica — fora de projeto trackfw não há trackfw ship como alternativa, e bloquear ali é custo
+# sem contrapartida. Custo medido: só parameter expansion e test -f por nível, nenhum fork de
+# processo; limitado pela profundidade do caminho.
+_TRACKFW_ROOT_DIR=$(pwd -P)
+_TRACKFW_FOUND=0
+while :; do
+  if [ -f "$_TRACKFW_ROOT_DIR/trackfw.yaml" ]; then
+    _TRACKFW_FOUND=1
+    break
+  fi
+  if [ "$_TRACKFW_ROOT_DIR" = "/" ]; then
+    break
+  fi
+  _TRACKFW_ROOT_DIR="\${_TRACKFW_ROOT_DIR%/*}"
+  if [ -z "$_TRACKFW_ROOT_DIR" ]; then
+    _TRACKFW_ROOT_DIR="/"
+  fi
+done
+[ "$_TRACKFW_FOUND" -eq 1 ] || exit 0
+
+# --- 1. Obter o comando git bruto ------------------------------------------------------------
+if [ "$#" -gt 0 ]; then
+  CMD_RAW="$*"
+else
+  INPUT="$_TRACKFW_STDIN"
+  TRIMMED=$(printf '%s' "$INPUT" | sed -e 's/^[[:space:]]*//')
+  case "$TRIMMED" in
+    \\{*)
+      CMD_RAW=""
+      if command -v jq >/dev/null 2>&1; then
+        CMD_RAW=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // .command // .tool_info.command_line // .hook_input.command // empty' 2>/dev/null || true)
+      fi
+      if [ -z "$CMD_RAW" ] || [ "$CMD_RAW" = "null" ]; then
+        CMD_RAW=$(printf '%s' "$INPUT" | sed -n 's/.*"tool_input"[[:space:]]*:[[:space:]]*{[^}]*"command"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p' | head -1)
+      fi
+      if [ -z "$CMD_RAW" ]; then
+        CMD_RAW=$(printf '%s' "$INPUT" | sed -n 's/.*"tool_info"[[:space:]]*:[[:space:]]*{[^}]*"command_line"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p' | head -1)
+      fi
+      if [ -z "$CMD_RAW" ]; then
+        CMD_RAW=$(printf '%s' "$INPUT" | sed -n 's/.*"hook_input"[[:space:]]*:[[:space:]]*{[^}]*"command"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p' | head -1)
+      fi
+      if [ -z "$CMD_RAW" ]; then
+        CMD_RAW=$(printf '%s' "$INPUT" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p' | head -1)
+      fi
+      ;;
+    *)
+      CMD_RAW="$INPUT"
+      ;;
+  esac
+fi
+
+if [ -z "$CMD_RAW" ]; then
+  CMD_RAW="\${TRACKFW_GIT_COMMAND:-}"
+fi
+
+[ -n "$CMD_RAW" ] || exit 0
+
+# --- 2. Pré-processamento anti-falso-positivo: neutraliza separadores reais (';', '&&',
+# '||', '|', quebra de linha) que estão DENTRO de aspas ou de corpo de heredoc, para que
+# conteúdo de mensagem (ex.: ` + "`" + `-m "linha 1\\nlinha 2"` + "`" + `) nunca seja fatiado em pseudo-segmentos
+# e lido como comando -------------------------------------------------------------------
+#
+# strip_heredoc_bodies: remove o CORPO de blocos heredoc (<<DELIM ... DELIM), preservando a
+# linha de abertura e a linha terminadora — cobre o padrão ` + "`" + `git commit -F- <<'EOF' ... EOF` + "`" + `
+# (heredoc não citado, fora do escopo de quote_aware_split abaixo). Heurística por linha, não
+# sintaxe completa de shell: só remove o corpo quando encontra a linha terminadora
+# correspondente. Se o heredoc nunca fecha (terminador ausente ou não localizado), devolve o
+# texto ORIGINAL sem qualquer alteração — lado seguro: mais restritivo é preferível a esconder
+# um comando real atrás de um heredoc mal-formado.
+strip_heredoc_bodies() {
+  printf '%s' "$1" | awk '
+    BEGIN {
+      dq = sprintf("%c", 34)
+      sq = sprintf("%c", 39)
+      in_heredoc = 0
+      delim = ""
+      ok = 1
+    }
+    {
+      raw = raw $0 "\\n"
+      if (in_heredoc) {
+        trimmed = $0
+        sub(/^[ \\t]+/, "", trimmed)
+        sub(/[ \\t]+$/, "", trimmed)
+        if (trimmed == delim) {
+          in_heredoc = 0
+          out = out $0 "\\n"
+        }
+        next
+      }
+      if (match($0, /<<-?[ \\t]*[^ \\t]+/)) {
+        d = substr($0, RSTART, RLENGTH)
+        sub(/^<<-?[ \\t]*/, "", d)
+        gsub(dq, "", d)
+        gsub(sq, "", d)
+        if (d != "") {
+          delim = d
+          in_heredoc = 1
+        }
+      }
+      out = out $0 "\\n"
+    }
+    END {
+      if (in_heredoc) ok = 0
+      if (ok) { printf "%s", out } else { printf "%s", raw }
+    }
+  '
+}
+
+# quote_aware_split: emite o texto com ';' isolado, '&&', '||' e '|' isolado convertidos em
+# quebra de linha — EXCETO quando ocorrem dentro de uma string entre aspas simples ou duplas,
+# caso em que são preservados como texto e uma quebra de linha real dentro das aspas vira
+# espaço (nunca gera um novo pseudo-segmento). Substitui o antigo ` + "`" + `sed` + "`" + ` cego, que não
+# distinguia texto citado de sintaxe de comando — a causa raiz do falso-positivo de linha de
+# mensagem de commit iniciada por "git ...". Aspas não fechadas até o fim da entrada
+# permanecem "abertas" até o fim — mesma semântica do shell real: uma aspa não fechada nunca
+# deixa o texto seguinte executar como comando novo, só torna o restante parte da mesma
+# string.
+quote_aware_split() {
+  printf '%s' "$1" | awk '
+    BEGIN {
+      dq = sprintf("%c", 34)
+      sq = sprintf("%c", 39)
+      bs = sprintf("%c", 92)
+      nl = sprintf("%c", 10)
+    }
+    { s = (NR == 1) ? $0 : s nl $0 }
+    END {
+      n = length(s)
+      q = ""
+      out = ""
+      i = 1
+      while (i <= n) {
+        c = substr(s, i, 1)
+        if (q != "") {
+          if (q == dq && c == bs && i < n) {
+            nx = substr(s, i + 1, 1)
+            out = out c (nx == nl ? " " : nx)
+            i += 2
+            continue
+          }
+          if (c == q) {
+            q = ""
+            out = out c
+            i++
+            continue
+          }
+          out = out (c == nl ? " " : c)
+          i++
+          continue
+        }
+        if (c == dq || c == sq) {
+          q = c
+          out = out c
+          i++
+          continue
+        }
+        if (substr(s, i, 2) == "&&" || substr(s, i, 2) == "||") {
+          out = out nl
+          i += 2
+          continue
+        }
+        if (c == ";" || c == "|") {
+          out = out nl
+          i++
+          continue
+        }
+        out = out c
+        i++
+      }
+      printf "%s", out
+    }
+  '
+}
+
+# match_subcommand — casa contra "git (commit|push|checkout -b|switch -c)", segmento por
+# segmento. Cada segmento é um comando real, obtido depois do pré-processamento acima
+# (strip_heredoc_bodies + quote_aware_split), que converte ';', '&&', '||', '|' fora de aspas
+# em quebra de linha e neutraliza os mesmos separadores quando aparecem dentro de
+# aspas/heredoc. "git" só conta se for o PRIMEIRO token do segmento (por basename, então
+# /usr/bin/git também casa) — nunca uma ocorrência solta em qualquer posição da string
+# inteira. Isso evita: (a) o segundo comando de uma cadeia escapar da checagem, (b) um path
+# absoluto para o git escapar por comparação de igualdade exata, e (c) texto de prosa —
+# inclusive linha de mensagem de commit que COMEÇA com "git <sub>" (ex.: uma tabela
+# documentando comandos bloqueados) — ser tratado como comando, porque esse texto agora nunca
+# produz um novo segmento. ` + "`" + `git switch -c/-C/--create` + "`" + ` (forma alternativa a ` + "`" + `checkout -b` + "`" + `
+# para criar branch) é reconhecido varrendo TODOS os tokens após o subcomando, não só o
+# primeiro — cobre ` + "`" + `git switch --track -c feat/x` + "`" + ` (flag antes de -c).
+# checkout -b é reconhecido do mesmo jeito: varre TODOS os tokens até achar -b/-B/--orphan,
+# não só o primeiro. Prefixos env e command antes de git são descartados antes da checagem do
+# basename — cobre env git push/command git push sem exigir tokenizar como o bash.
+match_subcommand() {
+  normalized=$(strip_heredoc_bodies "$1")
+  normalized=$(quote_aware_split "$normalized")
+  while IFS= read -r seg; do
+    seg_trimmed=$(printf '%s' "$seg" | sed -e 's/^[[:space:]]*//')
+    [ -n "$seg_trimmed" ] || continue
+
+    set -- $seg_trimmed
+    first="$1"
+    base="\${first##*/}"
+    while [ "$base" = "env" ] || [ "$base" = "command" ]; do
+      is_env="$base"
+      shift
+      [ "$#" -gt 0 ] || break
+      if [ "$is_env" = "env" ]; then
+        while [ "$#" -gt 0 ]; do
+          case "$1" in
+            -*)
+              break
+              ;;
+            *=*)
+              shift
+              ;;
+            *)
+              break
+              ;;
+          esac
+        done
+        [ "$#" -gt 0 ] || break
+      fi
+      first="$1"
+      base="\${first##*/}"
+    done
+    [ "$base" = "git" ] || continue
+    shift
+
+    sub=""
+    while [ "$#" -gt 0 ]; do
+      tok="$1"
+      case "$tok" in
+        -C|-c|--work-tree|--git-dir|--namespace)
+          if [ "$#" -ge 2 ]; then shift 2; else shift; fi
+          continue
+          ;;
+        -*)
+          shift
+          continue
+          ;;
+        *)
+          sub="$tok"
+          shift
+          break
+          ;;
+      esac
+    done
+
+    case "$sub" in
+      commit)
+        echo "commit"
+        return 0
+        ;;
+      push)
+        echo "push"
+        return 0
+        ;;
+      checkout)
+        for tok2 in "$@"; do
+          case "$tok2" in
+            -b|-B|--orphan|--orphan=*)
+              echo "checkout-b"
+              return 0
+              ;;
+          esac
+        done
+        ;;
+      switch)
+        for tok2 in "$@"; do
+          case "$tok2" in
+            -c|-C|--create|--create=*|--force-create|--force-create=*)
+              echo "switch-c"
+              return 0
+              ;;
+          esac
+        done
+        ;;
+      branch)
+        # git branch é majoritariamente leitura (sem args, -a, -r, -l, --list, -v/-vv,
+        # --show-current, --contains, --no-contains, --merged, --no-merged, --sort=,
+        # --format=, --points-at, -d/-D/--delete) — bloquear leitura seria pior que a
+        # brecha. Só bloqueia: (a) -c/-C/-m/-M/--copy/--move (cria/renomeia branch,
+        # qualquer posição de token) ou (b) um argumento posicional puro (nome da branch a
+        # criar), a menos que -d/-D/--delete também esteja presente (delete tem
+        # posicional legítimo — o nome a apagar). Flags de valor conhecidas (--contains,
+        # --no-contains, --sort, --format, --points-at, --merged, --no-merged) têm seu
+        # valor seguinte pulado quando vem em token separado, para não ser lido como
+        # posicional de criação.
+        branch_action=0
+        has_delete=0
+        saw_positional=0
+        skip_next=0
+        for tok2 in "$@"; do
+          if [ "$skip_next" = "1" ]; then
+            skip_next=0
+            continue
+          fi
+          case "$tok2" in
+            -c|-C|-m|-M|--copy|--copy=*|--move|--move=*)
+              branch_action=1
+              ;;
+            -d|-D|--delete|--delete=*)
+              has_delete=1
+              ;;
+            --contains|--no-contains|--sort|--format|--points-at|--merged|--no-merged)
+              skip_next=1
+              ;;
+            -*)
+              ;;
+            *)
+              saw_positional=1
+              ;;
+          esac
+        done
+        if [ "$has_delete" != "1" ]; then
+          if [ "$branch_action" = "1" ] || [ "$saw_positional" = "1" ]; then
+            echo "branch-create"
+            return 0
+          fi
+        fi
+        ;;
+      worktree)
+        if [ "\${1:-}" = "add" ]; then
+          shift
+          for tok2 in "$@"; do
+            case "$tok2" in
+              -b|-B)
+                echo "worktree-add-b"
+                return 0
+                ;;
+            esac
+          done
+        fi
+        ;;
+    esac
+  done <<EOF
+$normalized
+EOF
+  return 1
+}
+
+SUBCOMMAND=$(match_subcommand "$CMD_RAW") || exit 0
+
+case "$SUBCOMMAND" in
+  checkout-b)
+    REASON="trackfw: git checkout -b bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    ;;
+  switch-c)
+    REASON="trackfw: git switch -c bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    ;;
+  branch-create)
+    REASON="trackfw: git branch bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    ;;
+  worktree-add-b)
+    REASON="trackfw: git worktree add -b bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    ;;
+  commit)
+    REASON="trackfw: git commit bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw commit -m '<mensagem>'` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    ;;
+  push)
+    REASON="trackfw: git push bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw ship` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+printf '{"decision":"block","reason":"%s"}\\n' "$REASON"
+echo "$REASON" >&2
+exit 2
+`
+
+// validateGitBranchGuardScriptIntegrity é a regra "git_branch_guard_script_integrity": compara
+// scripts/trackfw-git-branch-guard.sh em disco contra o template que esta versão do trackfw
+// geraria. Espelha validateCredentialGuardScriptIntegrity exatamente — mesmo contrato de silêncio
+// na ausência (existência é responsabilidade de git_branch_guard_hook_resolvable, não desta regra).
+function validateGitBranchGuardScriptIntegrity(cwd) {
+  const root = cwd || process.cwd()
+  const relPath = 'scripts/trackfw-git-branch-guard.sh'
+  let content
+  try {
+    content = fs.readFileSync(path.join(root, relPath), 'utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT') return []
+    return [inspectionDiagnostic('git_branch_guard_script_integrity', relPath, e)]
+  }
+
+  if (content === GIT_BRANCH_GUARD_SCRIPT_REFERENCE) return []
+
+  return [
+    `${relPath} content diverges from the template this version of trackfw generates — ` +
+    'if you did not edit this file by hand, run `trackfw update` to regenerate it',
+  ]
+}
+
+// CREDENTIAL_GUARD_GLOBAL_SCRIPT_REFERENCE is a validator-local copy of the GLOBAL-scope
+// ~/.trackfw/scripts/trackfw-credential-guard.sh template composed in npm/src/generators/hooks.js
+// (GLOBAL_CREDENTIAL_GUARD_SCRIPT = CG_HEADER + CG_DETECTION_CORE + CG_GLOBAL_TAIL). This is a
+// DIFFERENT template than CREDENTIAL_GUARD_SCRIPT_REFERENCE (the project-scope variant): the
+// global variant omits the project-guard block ("no-op outside a trackfw.yaml project") and
+// defaults credential_guard.mode to "block" instead of "warn" — mirrors Go's
+// credentialGuardGlobalScriptReference
+// (internal/validator/validator_credential_guard_global_reference.go). Comparing the global
+// on-disk script against CREDENTIAL_GUARD_SCRIPT_REFERENCE (the project template) would be a
+// guaranteed false positive for every user with the global harness installed.
+const CREDENTIAL_GUARD_GLOBAL_SCRIPT_REFERENCE = `#!/usr/bin/env bash
+# trackfw credential guard — PreToolUse/PostToolUse hook
+set -euo pipefail
+
+INPUT=$(cat)
+
+JWT_PATTERN='eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+'
+AWS_KEY_PATTERN='AKIA[0-9A-Z]{16}'
+
+MATCH=""
+if printf '%s' "$INPUT" | grep -qE "$JWT_PATTERN"; then
+  MATCH="JWT"
+elif printf '%s' "$INPUT" | grep -qE "$AWS_KEY_PATTERN"; then
+  MATCH="AWS access key"
+fi
+
+# The raw payload is JSON: any double quote inside the underlying tool_input.command is
+# escaped as \\" -- unescape those before scanning for redirect targets, or a quoted target
+# like "$TMPFILE" is seen as starting with a literal backslash instead of a variable
+# reference.
+RAW=$(printf '%s' "$INPUT" | sed 's/\\\\"/"/g')
+
+# Ignore matches that are only ever written to an ephemeral destination
+# (mktemp-derived path or /dev/null). A match with no redirect at all
+# (printed to stdout, e.g.) or redirected to a plain file path still
+# alerts -- that is the incident this hook guards against.
+is_ephemeral_target() {
+  local target
+  target=$(printf '%s' "$1" | tr -d "\\"'" | sed -E 's/[},]+$//')
+  case "$target" in
+    /dev/null) return 0 ;;
+    *mktemp*) return 0 ;;
+  esac
+  if printf '%s' "$target" | grep -qE '^\\$\\{?[A-Za-z_][A-Za-z0-9_]*\\}?$'; then
+    local varname pattern
+    varname=$(printf '%s' "$target" | sed -E 's/^\\$\\{?([A-Za-z_][A-Za-z0-9_]*)\\}?$/\\1/')
+    pattern="*\${varname}="'$(mktemp'"*"
+    case "$RAW" in
+      $pattern) return 0 ;;
+    esac
+  fi
+  return 1
+}
+
+REDIRECTS=$(printf '%s' "$RAW" | grep -oE '[0-9]?>>?[[:space:]]*[^[:space:]|&;,:]+' || true)
+
+# Second detection layer: only runs when the payload scan above found nothing -- keeps the common
+# case (match already found) cheap and avoids reading files unnecessarily. Files above the size cap
+# are skipped silently.
+scan_file_for_pattern() {
+  local path size
+  path=$(printf '%s' "$1" | tr -d "\\"'" | sed -E 's/[},]+$//')
+  [ -n "$path" ] && [ -f "$path" ] || return 1
+  size=$(wc -c < "$path" 2>/dev/null | tr -d '[:space:]')
+  size=\${size:-0}
+  [ "$size" -lt 1048576 ] || return 1
+  if grep -qE "$JWT_PATTERN" "$path" 2>/dev/null; then
+    MATCH="JWT"
+    return 0
+  fi
+  if grep -qE "$AWS_KEY_PATTERN" "$path" 2>/dev/null; then
+    MATCH="AWS access key"
+    return 0
+  fi
+  return 1
+}
+
+if [ -z "$MATCH" ] && [ -n "$REDIRECTS" ]; then
+  while IFS= read -r line; do
+    if [ -z "$line" ]; then
+      continue
+    fi
+    target=$(printf '%s' "$line" | sed -E 's/^[0-9]?>>?[[:space:]]*//')
+    if ! is_ephemeral_target "$target"; then
+      scan_file_for_pattern "$target" && break
+    fi
+  done <<< "$REDIRECTS"
+fi
+
+if [ -z "$MATCH" ]; then
+  CMD_LINE=$(printf '%s' "$RAW" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p')
+  if [ -n "$CMD_LINE" ]; then
+    set -- $CMD_LINE
+    cmd_name="\${1:-}"
+    case "$cmd_name" in
+      cat|head|tail|jq|grep)
+        shift
+        for token in "$@"; do
+          scan_file_for_pattern "$token" && break
+        done
+        ;;
+    esac
+  fi
+fi
+
+[ -n "$MATCH" ] || exit 0
+
+HAS_REDIRECT=0
+EXEMPT=1
+if [ -n "$REDIRECTS" ]; then
+  while IFS= read -r line; do
+    if [ -z "$line" ]; then
+      continue
+    fi
+    HAS_REDIRECT=1
+    target=$(printf '%s' "$line" | sed -E 's/^[0-9]?>>?[[:space:]]*//')
+    if ! is_ephemeral_target "$target"; then
+      EXEMPT=0
+    fi
+  done <<< "$REDIRECTS"
+fi
+
+if [ "$HAS_REDIRECT" -eq 1 ] && [ "$EXEMPT" -eq 1 ]; then
+  exit 0
+fi
+
+DEFAULT_MODE="block"
+MODE=$(grep -A 5 '^credential_guard:' trackfw.yaml 2>/dev/null | grep 'mode:' | head -1 | sed -E 's/^[[:space:]]*mode:[[:space:]]*//; s/[[:space:]]*#.*$//' | tr -d "\\"'" || true)
+case "$MODE" in
+  warn|block) ;;
+  *) MODE="$DEFAULT_MODE" ;;
+esac
+
+if [ "$MODE" = "block" ]; then
+  echo "trackfw-credential-guard: blocked - possible $MATCH detected in tool payload." >&2
+  exit 2
+fi
+
+echo "trackfw-credential-guard: warning - possible $MATCH detected in tool payload." >&2
+
+ROADMAP_DIR="docs/roadmaps"
+if [ ! -d "$ROADMAP_DIR" ]; then
+  exit 0
+fi
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+MSG="Possible $MATCH detected in tool payload - review before materializing credentials in plain text."
+MSG_ESC=$(echo "$MSG" | tr -d '\\000-\\037' | sed 's/\\\\/\\\\\\\\/g; s/"/\\\\"/g')
+
+mkdir -p "$ROADMAP_DIR"
+printf '{"tool":"credential-guard","message":"%s","level":"action_required","timestamp":"%s"}\\n' \\
+  "$MSG_ESC" \\
+  "$TIMESTAMP" > "$ROADMAP_DIR/.trackfw-credential-guard.json"
+
+exit 0
+`
+
+// globalGuardConfigFile associates a GLOBAL (per-CLI, $HOME-rooted) hook/settings config file with
+// the CLI that consumes it, for the global-scope guard checks below. Distinct from
+// CREDENTIAL_GUARD_HOOK_FILES, whose relPath is rooted at the PROJECT root, not $HOME.
+//
+// GLOBAL_GUARD_CONFIG_FILES is the closed list of GLOBAL hook/settings files `trackfw update
+// harness` can write a guard entry into — the global-scope counterpart of
+// CREDENTIAL_GUARD_HOOK_FILES. Paths and CLI labels ported from Go's globalGuardConfigFiles
+// (internal/validator/validator_git_branch_guard.go) — note this list DIFFERS from
+// CREDENTIAL_GUARD_HOOK_FILES for Copilot and Kiro (global scope uses .copilot/settings.json and
+// .kiro/hooks/trackfw-credential-guard.json, not the project-scope attention-hook paths).
+// requiresCommandType (ROADMAP-2026-08-17 ML-4B) mirrors CREDENTIAL_GUARD_HOOK_FILES'
+// requiresCommandType above — true for every CLI except Cursor.
+const GLOBAL_GUARD_CONFIG_FILES = [
+  { relPath: '.claude/settings.json', cli: 'Claude Code', requiresCommandType: true },
+  { relPath: '.codex/hooks.json', cli: 'Codex CLI', requiresCommandType: true },
+  { relPath: '.gemini/settings.json', cli: 'Gemini CLI', requiresCommandType: true },
+  { relPath: '.cursor/hooks.json', cli: 'Cursor', requiresCommandType: false },
+  { relPath: '.copilot/settings.json', cli: 'GitHub Copilot CLI', requiresCommandType: true },
+  { relPath: '.kiro/hooks/trackfw-credential-guard.json', cli: 'Kiro', requiresCommandType: true },
+]
+
+// globalGuardConfigPath resolves the actual on-disk path (relative to $HOME) that
+// validateGuardGlobalHookResolvable must read for a given (GLOBAL_GUARD_CONFIG_FILES entry,
+// scriptMarker) pair. Port of Go's globalGuardConfigPath (internal/validator/
+// validator_git_branch_guard.go) — see that function's doc comment for the full rationale
+// (5 CLIs share one merge-based file across both guards; Kiro is the sole exception, with a
+// dedicated file per guard because its writer rewrites the whole document wholesale).
+//
+// ROADMAP-2026-08-17 ML-3B: before this function existed, GLOBAL_GUARD_CONFIG_FILES only ever
+// pointed Kiro at trackfw-credential-guard.json for BOTH guards, so git_branch_guard_hook_resolvable
+// never inspected ~/.kiro/hooks/trackfw-git-branch-guard.json at all.
+function globalGuardConfigPath(gf, scriptMarker) {
+  if (gf.cli === 'Kiro' && scriptMarker === GIT_BRANCH_GUARD_SCRIPT_MARKER) {
+    return '.kiro/hooks/trackfw-git-branch-guard.json'
+  }
+  return gf.relPath
+}
+
+// validateGuardGlobalHookResolvable is the GLOBAL-scope counterpart of
+// validateGuardHookResolvable: for each of the 6 GLOBAL_GUARD_CONFIG_FILES that exists AND
+// references scriptMarker, verifies the referenced script exists and is executable. Port of Go's
+// validateGuardGlobalHookResolvable (internal/validator/validator_git_branch_guard.go) — see that
+// function's doc comment for the full trigger-condition and fail-open rationale.
+//
+// Global entries are written by npm/src/generators (harnessCredentialGuardTarget*-equivalent code
+// in agentfiles-equivalent generators) as fully resolved absolute paths, never a placeholder like
+// $CLAUDE_PROJECT_DIR — so, unlike the project-scope resolveCredentialGuardHookPath, no
+// 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.
+function validateGuardGlobalHookResolvable(scriptMarker) {
+  const home = os.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
+    try {
+      content = fs.readFileSync(fullPath, 'utf8')
+    } catch (e) {
+      if (e.code === 'ENOENT') continue
+      continue
+    }
+
+    let parsed
+    try {
+      parsed = JSON.parse(content)
+    } catch (_) {
+      continue
+    }
+
+    const commands = []
+    collectCommandsWithMarker(parsed, scriptMarker, commands)
+
+    const seen = new Set()
+    for (const m of commands) {
+      const seenKey = `${m.raw} ${m.typeIsCommand}`
+      if (seen.has(seenKey)) continue
+      seen.add(seenKey)
+
+      if (!path.isAbsolute(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
+      // version, another tool's merge) is silently never executed by the CLI, even though the
+      // script itself exists and is fine. Reported instead of the exists/executable checks below,
+      // which assume the entry is structurally valid.
+      if (gf.requiresCommandType && !m.typeIsCommand) {
+        msgs.push(`~/${relPath} (${gf.cli}, global scope) references ${scriptMarker} resolved to "${m.raw}", but the hook entry is missing "type":"command" (or has an invalid type) — ${gf.cli} will silently never execute it; run \`trackfw update harness\` to regenerate it`)
+        continue
+      }
+
+      let stat = null
+      try {
+        stat = fs.statSync(m.raw)
+      } catch (_) {
+        stat = null
+      }
+
+      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) {
+        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`)
+      }
+    }
+  }
+
+  return msgs
+}
+
+// validateGuardGlobalScriptIntegrity is the GLOBAL-scope counterpart of
+// validateCredentialGuardScriptIntegrity/validateGitBranchGuardScriptIntegrity: verifies the
+// content of ~/.trackfw/scripts/<scriptFileName> (the fixed location the global generators write
+// to) against referenceContent byte-for-byte. Port of Go's validateGuardGlobalScriptIntegrity
+// (internal/validator/validator_git_branch_guard.go).
+//
+// ROADMAP-2026-08-17 (guard global cabeado com no-op / integridade independente de fiação), ML-3A:
+// deliberately triggers on ARTIFACT EXISTENCE, not on any GLOBAL_GUARD_CONFIG_FILES entry
+// referencing scriptMarker — the old per-config trigger meant a script trackfw itself wrote (via
+// `trackfw update harness`) but that no config yet pointed at could rot indefinitely with
+// `validate` green. "If trackfw wrote the script, trackfw verifies the script" — existence is the
+// only precondition; wiring is irrelevant to whether the artifact itself has drifted.
+//
+// Fail-open on absence: a script trackfw never wrote (user never ran `update harness`) is not an
+// error.
+//
+// Single evaluation per script (not per referencing config): caps the message count at 1
+// regardless of how many (or how few — including zero) configs reference the same on-disk path —
+// this is what prevents double-reporting now that git-branch-guard has both global wiring (Wave 2)
+// and a global artifact.
+//
+// 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()
+  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 []
+  }
+
+  if (content === referenceContent) return []
+
+  return [`${scriptPath} (global scope) content diverges from the template this version of trackfw generates — if you did not edit this file by hand, run \`trackfw update harness\` to regenerate it`]
+}
+
+// validateCredentialGuardGlobalHookResolvable / validateCredentialGuardGlobalScriptIntegrity /
+// validateGitBranchGuardGlobalHookResolvable / validateGitBranchGuardGlobalScriptIntegrity are the
+// 4 thin wrappers wired in validateUnfiltered below — each folds its messages into the SAME rule
+// name as its project-scope counterpart (credential_guard_hook_resolvable,
+// credential_guard_script_integrity, git_branch_guard_hook_resolvable,
+// git_branch_guard_script_integrity respectively), so no new rules: entries in trackfw.yaml are
+// needed. Port of the 4 equivalent wrappers in
+// internal/validator/validator_git_branch_guard.go.
+function validateCredentialGuardGlobalHookResolvable() {
+  return validateGuardGlobalHookResolvable(CREDENTIAL_GUARD_SCRIPT_MARKER)
+}
+
+function validateCredentialGuardGlobalScriptIntegrity() {
+  return validateGuardGlobalScriptIntegrity(CREDENTIAL_GUARD_SCRIPT_MARKER, CREDENTIAL_GUARD_GLOBAL_SCRIPT_REFERENCE)
+}
+
+function validateGitBranchGuardGlobalHookResolvable() {
+  return validateGuardGlobalHookResolvable(GIT_BRANCH_GUARD_SCRIPT_MARKER)
+}
+
+function validateGitBranchGuardGlobalScriptIntegrity() {
+  return validateGuardGlobalScriptIntegrity(GIT_BRANCH_GUARD_SCRIPT_MARKER, GIT_BRANCH_GUARD_SCRIPT_REFERENCE)
+}
+// NOTE: CREDENTIAL_GUARD_SCRIPT_MARKER === 'trackfw-credential-guard.sh' and
+// GIT_BRANCH_GUARD_SCRIPT_MARKER === 'trackfw-git-branch-guard.sh' — both markers are already the
+// literal script filenames, so they double as scriptFileName above with no extra constant needed
+// (same reuse the Go port relies on).
+
 // CREDENTIAL_GUARD_MODE_LOOKBEHIND_LINES mirrors the shell script's own resolution of
 // credential_guard.mode (`grep -A 5 '^credential_guard:'`): the mode key is found on the matched
 // line or within the 5 lines following it.
@@ -1600,6 +2485,12 @@ const RULE_DEFAULTS = {
   // credential_guard_mode_downgrade is deliberately absent: it falls through to ruleSeverity's
   // 'error' default.
   credential_guard_script_integrity: 'warning',
+  // ROADMAP-2026-08-15-trackfw-validate-deve-detectar-scripts-de-hook-ausentes-ou-desatualizados,
+  // ML-2A: same rationale as credential_guard_script_integrity above — the script carries no
+  // version marker, so this rule cannot tell legitimate drift from tampering.
+  // 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',
 }
 
 // ROADMAP-2026-08-12-ancorar-rules-no-head-para-as-regras-de-credential-guard, ML-1A.
@@ -1719,6 +2610,122 @@ function saveBaseline(violations, warnings) {
   fs.writeFileSync(BASELINE_FILE, JSON.stringify(bf, null, 2), 'utf8')
 }
 
+function sha256Hex(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex')
+}
+
+// THIRDPARTY_ORIGIN é o valor de Claim.origin que marca um artefato do manifest como instalado
+// por `third-party install` (ADR-2026-08-15 D11).
+const THIRDPARTY_ORIGIN = 'thirdparty'
+
+// validateThirdPartyArtifactHasProvenance implementa a regra "thirdparty_artifact_has_provenance"
+// (ADR-2026-08-15 D2) — a detecção real, ancorada em git, por trás do guardrail
+// TRACKFW_ORCHESTRATOR_SESSION. NUNCA faz fetch de rede (D6): lê só
+// .trackfw/integrations-manifest.json, .trackfw/thirdparty-provenance.json e
+// .trackfw/thirdparty-quarantine/<checksum>.json, todos já em disco (e, por convenção deste
+// projeto, versionados no repositório).
+//
+// Duas ramificações, ambas fatais (error — a regra está deliberadamente ausente de RULE_DEFAULTS):
+//   1. um artifact do manifest carrega um claim com origin === "thirdparty" mas
+//      thirdparty-provenance.json não tem entrada chaveada por aquele destino;
+//   2. existe entrada de proveniência, mas seu installed_sha256 não pode ser reconciliado com o que
+//      de fato está em disco no destino declarado.
+//
+// Sobre a ramificação 2 (ADR-2026-08-15 D2-bis, ML-3B) — checksum_sha256 é sha256 dos bytes BRUTOS
+// (D6), mas o arquivo instalado é sempre NormalizeThirdPartyContent(raw) — não é a função
+// identidade em geral, então comparar checksum_sha256 direto contra sha256(arquivo instalado)
+// produz falso-positivo em toda instalação legítima cujo conteúdo bruto não fosse já exatamente
+// TrimSpace+newline único. A resolução ML-3A usava o registro de quarentena como ponte entre os
+// dois domínios — correta, mas tornava um artefato de ESTÁGIO (.trackfw/thirdparty-quarantine/,
+// destinado a ser podado) dependência obrigatória de um gate PERMANENTE. D2-bis resolve isso com
+// um segundo campo na entrada de proveniência, installed_sha256 = sha256(bytes NORMALIZADOS),
+// calculado no momento do install pelo mesmo código que grava o arquivo (npm/src/commands/thirdparty.js).
+// checksum_sha256 permanece intocado, é a âncora de aprovação D8c. A ramificação 2 agora compara
+// sha256(arquivo instalado) diretamente contra entry.installed_sha256 — dois domínios já
+// normalizados, sem ponte via quarentena. A ausência da quarentena deixou de ser erro desta regra.
+function validateThirdPartyArtifactHasProvenance(cwd) {
+  const root = cwd || process.cwd()
+
+  const manifestPath = path.join(root, '.trackfw', 'integrations-manifest.json')
+  let manifest
+  try {
+    const raw = fs.readFileSync(manifestPath, 'utf8')
+    manifest = JSON.parse(raw)
+  } catch (err) {
+    if (err.code === 'ENOENT') return []
+    throw new Error(`thirdparty_artifact_has_provenance: read ${manifestPath}: ${err.message}`)
+  }
+
+  const destinations = []
+  for (const [destination, artifact] of Object.entries(manifest.artifacts || {})) {
+    const claims = artifact.claims || []
+    if (claims.some(claim => claim.origin === THIRDPARTY_ORIGIN)) destinations.push(destination)
+  }
+  if (destinations.length === 0) return []
+  destinations.sort()
+
+  let prov
+  try {
+    prov = loadProvenance(root)
+  } catch (err) {
+    throw new Error(`thirdparty_artifact_has_provenance: ${err.message}`)
+  }
+
+  const msgs = []
+  for (const destination of destinations) {
+    // Provenance keys are NOT the manifest's absolute destination —
+    // verified empirically against the real install command
+    // (npm/src/commands/thirdparty.js): verifyApproval/upsertProvenanceEntry
+    // are called with the project-root-relative (or "~/"-prefixed,
+    // global-scope) destination string BEFORE IntegrationManager.resolve()
+    // joins it against root to produce the absolute manifest key. Every
+    // claim reached here came from the PROJECT manifest, so its scope is
+    // always "project" (a global-scope claim lives in the home manifest
+    // 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)
+    const entry = (prov.entries || {})[provenanceKey]
+    if (!entry) {
+      msgs.push(
+        `thirdparty_artifact_has_provenance: "${destination}" is claimed as a third-party artifact but has no ` +
+        'entry in .trackfw/thirdparty-provenance.json — obtain a favorable hades-tf review and record an ' +
+        'approved provenance entry for this destination before this can pass validate (D2 branch i)'
+      )
+      continue
+    }
+
+    let installed
+    try {
+      installed = fs.readFileSync(destination)
+    } catch (err) {
+      msgs.push(
+        `thirdparty_artifact_has_provenance: "${destination}" is claimed as a third-party artifact with an ` +
+        `approved provenance entry, but the destination file could not be read (${err.message})`
+      )
+      continue
+    }
+
+    // entry.installed_sha256 may be `undefined` (key absent — e.g. an
+    // approver-authored entry from before `install` ever ran, or a partial
+    // install that failed between manager.Install and the installed_sha256
+    // upsert). Coerce to '' so the comparison and the message text match
+    // Go (zero-value "") and Python (.get(..., "")) byte-for-byte — do NOT
+    // interpolate entry.installed_sha256 directly, that renders the
+    // JS-only literal "undefined" into the violation message.
+    const installedSHA256 = entry.installed_sha256 || ''
+    if (sha256Hex(installed) !== installedSHA256) {
+      msgs.push(
+        `thirdparty_artifact_has_provenance: "${destination}" — installed content does not match ` +
+        `installed_sha256 ${installedSHA256} recorded in .trackfw/thirdparty-provenance.json — the ` +
+        'artifact was modified after approval or installed outside the fetch/install flow (D2 branch ii, D2-bis)'
+      )
+    }
+  }
+
+  return msgs
+}
+
 // validateUnfiltered executa todas as validações e retorna { violations, warnings } sem ratchet.
 async function validateUnfiltered() {
   resetMeta()
@@ -1740,9 +2747,18 @@ async function validateUnfiltered() {
   applyRule('blocked_by_draft_adr', validateREQsNotBlockedByDraftADRs(),  violations, warnings)
   applyRule('adr_accepted_when_req_done', validateADRAcceptedWhenREQDone(), violations, warnings)
   applyRule('note_orphan',           validateNoteOrphan(),                 violations, warnings)
-  applyRule('credential_guard_hook_resolvable', validateCredentialGuardHookResolvable(), violations, warnings)
-  applyRule('credential_guard_script_integrity', validateCredentialGuardScriptIntegrity(), violations, warnings)
+  applyRule('credential_guard_hook_resolvable', validateCredentialGuardHookResolvable().concat(validateCredentialGuardGlobalHookResolvable()), violations, warnings)
+  applyRule('credential_guard_script_integrity', validateCredentialGuardScriptIntegrity().concat(validateCredentialGuardGlobalScriptIntegrity()), violations, warnings)
   applyRule('credential_guard_mode_downgrade', validateCredentialGuardModeDowngrade(), violations, warnings)
+  // ROADMAP-2026-08-15-trackfw-validate-deve-detectar-scripts-de-hook-ausentes-ou-desatualizados,
+  // ML-2A — port de internal/validator/validator.go's wiring das 4 regras/wrappers em
+  // validator_git_branch_guard.go.
+  applyRule('git_branch_guard_hook_resolvable', validateGitBranchGuardHookResolvable().concat(validateGitBranchGuardGlobalHookResolvable()), violations, warnings)
+  applyRule('git_branch_guard_script_integrity', validateGitBranchGuardScriptIntegrity().concat(validateGitBranchGuardGlobalScriptIntegrity()), violations, warnings)
+
+  // ADR-2026-08-15-gate-de-duas-fases-..., ML-3A (D2): detecção ancorada em git por trás do
+  // guardrail TRACKFW_ORCHESTRATOR_SESSION.
+  applyRule('thirdparty_artifact_has_provenance', validateThirdPartyArtifactHasProvenance(), violations, warnings)
 
   // Regras configuráveis via applyRule (popula _itemMeta automaticamente)
   applyRule('req_has_adr',          validateREQsHaveADR(),          violations, warnings)
@@ -2012,4 +3028,21 @@ module.exports = {
   validateCredentialGuardModeDowngrade,
   extractCredentialGuardMode,
   CREDENTIAL_GUARD_SCRIPT_REFERENCE,
+  // ROADMAP-2026-08-15-trackfw-validate-deve-detectar-scripts-de-hook-ausentes-ou-desatualizados,
+  // ML-2A
+  collectCommandsWithMarker,
+  validateGuardHookResolvable,
+  validateGitBranchGuardHookResolvable,
+  validateGitBranchGuardScriptIntegrity,
+  GIT_BRANCH_GUARD_SCRIPT_REFERENCE,
+  CREDENTIAL_GUARD_GLOBAL_SCRIPT_REFERENCE,
+  GLOBAL_GUARD_CONFIG_FILES,
+  validateGuardGlobalHookResolvable,
+  validateGuardGlobalScriptIntegrity,
+  // ROADMAP-2026-08-15-instalacao-de-skills-de-terceiro-via-url-para-agentes-especialistas, ML-3A
+  validateThirdPartyArtifactHasProvenance,
+  validateCredentialGuardGlobalHookResolvable,
+  validateCredentialGuardGlobalScriptIntegrity,
+  validateGitBranchGuardGlobalHookResolvable,
+  validateGitBranchGuardGlobalScriptIntegrity,
 }