trackfw 7.0.0 → 7.2.0

package/src/validator/index.js

@@ -1167,13 +1167,28 @@ const GIT_BRANCH_GUARD_SCRIPT_MARKER = 'trackfw-git-branch-guard.sh'
 // -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.
+//
+// requiresVarOrShellPrefix (ROADMAP-2026-08-21 ML-1B, port of Go's
+// credentialGuardHookFile.requiresVarOrShellPrefix): true for Claude/Codex/Gemini — the
+// ADR-2026-08-11 requires these CLIs to anchor the hook path with $VAR/... or "$(git ...)/..."
+// because their hooks run from the agent's cwd, not necessarily the project root. A bare
+// relative path ("scripts/...") silently fails from any subdirectory (REQ-2026-08-17 root
+// cause). false for Cursor/Copilot/Kiro, where the bare relative path IS the correct form —
+// flagging them would be a false-positive (the dominant risk of this REQ).
 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, requiresVarOrShellPrefix: true },
+  { relPath: '.codex/hooks.json', cli: 'Codex CLI', requiresCommandType: true, requiresVarOrShellPrefix: true },
+  { relPath: '.gemini/settings.json', cli: 'Gemini CLI', requiresCommandType: true, requiresVarOrShellPrefix: true },
+  { relPath: '.cursor/hooks.json', cli: 'Cursor', requiresCommandType: false, requiresVarOrShellPrefix: false },
+  { relPath: '.github/hooks/trackfw-attention.json', cli: 'GitHub Copilot CLI', requiresCommandType: true, requiresVarOrShellPrefix: false },
+  { relPath: '.kiro/hooks/trackfw-attention.json', cli: 'Kiro', requiresCommandType: true, requiresVarOrShellPrefix: false },
 ]
 
 // resolveCredentialGuardHookPath resolve o valor bruto de um comando de hook (string extraída do
@@ -1205,20 +1220,97 @@ function resolveCredentialGuardHookPath(raw, root) {
     const inner = raw.slice(codexPrefix.length, raw.length - 1)
     return path.join(root, inner)
   }
-  if (!raw.startsWith('$') && !raw.startsWith('"') && !path.isAbsolute(raw)) {
+  if (!raw.startsWith('$') && !raw.startsWith('"') && !path.isAbsolute(raw) && !raw.startsWith('~/')) {
     // Caminho relativo puro — Cursor (beforeShellExecution/preToolUse), GitHub Copilot CLI
     // (campo "bash"), Kiro (action.command).
+    // ~/… é excluído: é classe 1 (tilde expande para $HOME — ancorado) mas o validator não expande
+    // o til; ok=false (null) silencia sem acusar.
     return path.join(root, raw)
   }
   return null
 }
 
+// HOOK_ANCHORAGE_CLASS_* classifica a semântica de ancoragem de um valor de comando de hook.
+// Avaliada apenas para CLIs com requiresVarOrShellPrefix=true. Decisão: ADR-2026-08-22.
+const HOOK_ANCHORAGE_CLASS_ANCHORED      = 1
+const HOOK_ANCHORAGE_CLASS_CWD_DEPENDENT = 2
+const HOOK_ANCHORAGE_CLASS_UNDECIDABLE   = 3
+
+// stripOuterQuotesForClassify remove aspas duplas envolventes de raw, se presentes. Necessário
+// porque "$PWD/scripts/…" entre aspas (achado D.3) deve receber o mesmo veredito que $PWD/…
+// sem aspas: as aspas são sintaxe, não semântica de ancoragem.
+function stripOuterQuotesForClassify(raw) {
+  if (raw.length >= 2 && raw[0] === '"' && raw[raw.length - 1] === '"') {
+    return raw.slice(1, raw.length - 1)
+  }
+  return raw
+}
+
+// hookValueWasQuoted reporta se raw tinha aspas duplas externas que stripOuterQuotesForClassify
+// removeria. Usado para distinguir ~/… (tilde expande para $HOME — classe 1) de "~/…" (tilde
+// NÃO expande dentro de aspas duplas — classe 2).
+function hookValueWasQuoted(raw) {
+  return raw.length >= 2 && raw[0] === '"' && raw[raw.length - 1] === '"'
+}
+
+// classifyHookAnchorage retorna a classe de ancoragem de rawStripped (com aspas externas já
+// removidas). wasQuoted indica se o valor original tinha aspas externas (obtido com
+// hookValueWasQuoted antes de chamar stripOuterQuotesForClassify). Ver HOOK_ANCHORAGE_CLASS_*
+// e ADR-2026-08-22.
+function classifyHookAnchorage(rawStripped, wasQuoted) {
+  // Classe 1 — ancora na raiz do projeto.
+  if (
+    rawStripped.startsWith('$CLAUDE_PROJECT_DIR/') ||
+    rawStripped.startsWith('$GEMINI_PROJECT_DIR/') ||
+    rawStripped.startsWith('$(git rev-parse --show-toplevel)/') ||
+    path.isAbsolute(rawStripped)
+  ) {
+    return HOOK_ANCHORAGE_CLASS_ANCHORED
+  }
+  // ~/… sem aspas: tilde expande para $HOME em qualquer shell POSIX — semanticamente ancorado.
+  // "~/…" com aspas: tilde NÃO expande dentro de aspas duplas, logo a forma quebra — classe 2.
+  if (rawStripped.startsWith('~/') && !wasQuoted) {
+    return HOOK_ANCHORAGE_CLASS_ANCHORED
+  }
+  // Classe 2 — expande a partir do cwd.
+  // ${PWD}/… tem a mesma semântica de $PWD/… (PWD é mandado pelo POSIX, sempre o cwd).
+  if (
+    rawStripped.startsWith('$PWD/') ||
+    rawStripped.startsWith('${PWD}/') ||
+    rawStripped.startsWith('./') ||
+    rawStripped.startsWith('../') ||
+    (!rawStripped.startsWith('$') && !path.isAbsolute(rawStripped))
+  ) {
+    return HOOK_ANCHORAGE_CLASS_CWD_DEPENDENT
+  }
+  // Classe 3 — indecidível; silêncio declarado.
+  return HOOK_ANCHORAGE_CLASS_UNDECIDABLE
+}
+
+// cwdDependentReason retorna o sufixo de mensagem específico por forma para violações de
+// classe 2, iniciando em "with a …". Dois formatos: formas contendo $PWD ou ${PWD} (em qualquer
+// posição, inclusive em wrappers sh -c / env) recebem a mensagem do $PWD; demais recebem
+// "bare relative path". Usa includes (não startsWith) para cobrir sh -c "$PWD/…" e env FOO=x $PWD/….
+function cwdDependentReason(rawStripped) {
+  if (rawStripped.includes('$PWD') || rawStripped.includes('${PWD}')) {
+    return 'with a $PWD path — $PWD expands to the current working directory, not the project root; run `trackfw update` to fix it'
+  }
+  return "with a bare relative path — this command only resolves from the project root and will silently fail when the agent's cwd is a subdirectory; run `trackfw update` to fix it"
+}
+
 // 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.
+// 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.
+// 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
@@ -1227,7 +1319,10 @@ function resolveCredentialGuardHookPath(raw, root) {
 // 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(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)) {
@@ -1235,7 +1330,15 @@ function collectCommandsWithMarker(value, marker, out) {
     return
   }
   if (value && typeof value === 'object') {
-    for (const key of Object.keys(value)) collectCommandsWithMarker(value[key], marker, 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)
+    }
   }
 }
 
@@ -1293,13 +1396,36 @@ function validateGuardHookResolvable(scriptMarker, cwd) {
     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)
+
+      // ADR-2026-08-22: classificar por ancoragem ANTES de resolver. Aspas externas são
+      // sintaxe, não semântica — removê-las antes garante que "$PWD/…" receba o mesmo veredito.
+      // wasQuoted distingue ~/… (classe 1) de "~/…" (classe 2).
+      const wasQuoted = hookValueWasQuoted(m.raw)
+      const rawStripped = stripOuterQuotesForClassify(m.raw)
+      const anchorageClass = classifyHookAnchorage(rawStripped, wasQuoted)
+      if (hf.requiresVarOrShellPrefix && anchorageClass === HOOK_ANCHORAGE_CLASS_CWD_DEPENDENT) {
+        msgs.push(`${hf.relPath} (${hf.cli}) references ${scriptMarker} ${cwdDependentReason(rawStripped)}`)
+        continue
+      }
 
-      const resolved = resolveCredentialGuardHookPath(raw, root)
+      // Classe 1 (ancorado) e classe 3 (indecidível) prosseguem para a resolução existente.
+      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)
@@ -1568,15 +1694,63 @@ const GBG_REF_BACKTICK = '\\`'
 // (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 brutos por subagente
+# 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=$(cat 2>/dev/null || true)
+  INPUT="$_TRACKFW_STDIN"
   TRIMMED=$(printf '%s' "$INPUT" | sed -e 's/^[[:space:]]*//')
   case "$TRIMMED" in
     \\{*)
@@ -1609,15 +1783,143 @@ fi
 
 [ -n "$CMD_RAW" ] || exit 0
 
-# --- 2. Casar contra "git (commit|push|checkout -b)", segmento por segmento -----------------
-# Cada segmento é um comando real (dividido por ; && || | e por quebra de linha). "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 (ex.: mensagem de commit mencionando
-# "git commit" no meio de uma frase) ser tratado como comando.
+# --- 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=$(printf '%s' "$1" | sed -e 's/&&/\\n/g' -e 's/||/\\n/g' -e 's/[;|]/\\n/g')
+  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
@@ -1625,6 +1927,29 @@ match_subcommand() {
     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
 
@@ -1658,11 +1983,217 @@ match_subcommand() {
         return 0
         ;;
       checkout)
-        if [ "\${1:-}" = "-b" ]; then
-          echo "checkout-b"
+        for tok2 in "$@"; do
+          case "$tok2" in
+            -b|-B|--orphan|--orphan=*)
+              echo "checkout-b"
+              return 0
+              ;;
+          esac
+        done
+        # git checkout -- <path> | git checkout . descarta alterações não commitadas do
+        # caminho indicado, de forma irreversível, no worktree compartilhado — bloqueia
+        # quando '--' aparece em qualquer posição (forma explícita de pathspec) ou quando
+        # '.' aparece como token isolado. 'git checkout <branch>' sem nenhum dos dois
+        # segue liberado por decisão (distinguir branch de caminho sem '--' é ambíguo, e
+        # adivinhar produziria falso-positivo).
+        checkout_path=0
+        for tok2 in "$@"; do
+          case "$tok2" in
+            --|.)
+              checkout_path=1
+              ;;
+          esac
+        done
+        if [ "$checkout_path" = "1" ]; then
+          echo "checkout-path"
+          return 0
+        fi
+        ;;
+      switch)
+        for tok2 in "$@"; do
+          case "$tok2" in
+            -c|-C|--create|--create=*|--force-create|--force-create=*)
+              echo "switch-c"
+              return 0
+              ;;
+          esac
+        done
+        ;;
+      stash)
+        # git stash: liberado só para leitura (list/show) — bloqueia a forma bare
+        # (equivale a "push"), push, save, clear e drop. Decisão de KG: bloquear a
+        # classe inteira, não só os literais medidos (ver REQ). Repositório com um único
+        # worktree compartilhado entre subagentes paralelos — um stash de um agente
+        # remove as alterações não commitadas de todos os outros.
+        stash_sub="\${1:-}"
+        case "$stash_sub" in
+          list|show)
+            ;;
+          *)
+            echo "stash"
+            return 0
+            ;;
+        esac
+        ;;
+      reset)
+        # Só --hard bloqueia, em qualquer posição de token — --soft/--mixed (inclusive
+        # sem flag, que é --mixed implícito) seguem liberados: --soft é o contorno
+        # padrão para reempurrar trabalho staged via ` + "`" + `trackfw ship -m "..."` + "`" + ` (ainda falta commitar após --soft).
+        for tok2 in "$@"; do
+          case "$tok2" in
+            --hard)
+              echo "reset-hard"
+              return 0
+              ;;
+          esac
+        done
+        ;;
+      clean)
+        # Bloqueia qualquer forma com force (-f, -fd, -fx, --force) ou -x/-X, EXCETO
+        # quando -n/--dry-run também está presente (dry-run nunca apaga nada).
+        clean_dry=0
+        clean_force=0
+        for tok2 in "$@"; do
+          case "$tok2" in
+            -n|--dry-run)
+              clean_dry=1
+              ;;
+            -f*|--force|--force=*|-x|-X)
+              clean_force=1
+              ;;
+          esac
+        done
+        if [ "$clean_dry" != "1" ] && [ "$clean_force" = "1" ]; then
+          echo "clean-force"
           return 0
         fi
         ;;
+      restore)
+        # git restore --staged SOZINHO nunca toca o working tree (mexe só no
+        # index), então segue liberado mesmo com path. Mas --worktree/-W (com ou
+        # sem --staged junto) SEMPRE afeta o working tree — inclusive
+        # "--staged --worktree", que restaura os dois — então bloqueia sempre que
+        # --worktree/-W aparecer, e também no caso padrão (sem --staged em
+        # nenhuma forma) com um argumento posicional (o path).
+        restore_staged=0
+        restore_worktree=0
+        restore_positional=0
+        for tok2 in "$@"; do
+          case "$tok2" in
+            --staged)
+              restore_staged=1
+              ;;
+            --worktree|-W)
+              restore_worktree=1
+              ;;
+            -*)
+              ;;
+            *)
+              restore_positional=1
+              ;;
+          esac
+        done
+        if [ "$restore_positional" = "1" ]; then
+          if [ "$restore_worktree" = "1" ] || [ "$restore_staged" != "1" ]; then
+            echo "restore-path"
+            return 0
+          fi
+        fi
+        ;;
+      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
+        elif [ "\${1:-}" = "remove" ]; then
+          # git worktree remove SEM -f/--force já recusa sozinho quando há alteração não
+          # commitada no worktree indicado — só a forma com force é irreversível o bastante
+          # para bloquear aqui.
+          shift
+          for tok2 in "$@"; do
+            case "$tok2" in
+              -f|--force)
+                echo "worktree-remove-force"
+                return 0
+                ;;
+            esac
+          done
+        fi
+        ;;
+      update-ref)
+        # git update-ref reescreve um ref (inclusive refs/remotes/origin/*) sem tocar o
+        # objeto apontado nem exigir push — foi o mecanismo que tornou alcançável o exploit
+        # descrito no ADR-2026-08-19-caminho-governado-para-push-forcado-e-tag-de-release.md
+        # (Emenda 1): forjar origin/<base> localmente para desviar o commit-alvo de trackfw
+        # release tag. Sem forma de leitura equivalente a bloquear seletivamente — a
+        # subcommand inteira é escrita — bloqueia sempre, sem exceção de token.
+        echo "update-ref"
+        return 0
+        ;;
+      rm)
+        # git rm -f/--force apaga do working tree e do index de forma irreversível, mesma
+        # classe de git clean -f/git reset --hard já bloqueados acima — sem exceção para
+        # --cached (destrancar do index sem -f já segue liberado por não precisar de force).
+        for tok2 in "$@"; do
+          case "$tok2" in
+            -f*|--force|--force=*)
+              echo "rm-force"
+              return 0
+              ;;
+          esac
+        done
+        ;;
     esac
   done <<EOF
 $normalized
@@ -1674,13 +2205,46 @@ 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."
+    REASON="trackfw: git checkout -b bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). 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 + `. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  branch-create)
+    REASON="trackfw: git branch bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). 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 + `. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). 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."
+    REASON="trackfw: git commit bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw commit -m '<mensagem>'` + GBG_REF_BACKTICK + `. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
     ;;
   push)
-    REASON="trackfw: git push bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw ship` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git push bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw push` + GBG_REF_BACKTICK + ` (para empurrar commits já criados), ` + GBG_REF_BACKTICK + `trackfw ship` + GBG_REF_BACKTICK + ` (para commit+push+PR em uma etapa) ou ` + GBG_REF_BACKTICK + `trackfw release tag` + GBG_REF_BACKTICK + ` (para publicar uma tag de release). Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  stash)
+    REASON="trackfw: git stash bruto bloqueado — worktree compartilhado entre subagentes, um stash remove as alterações não commitadas de todos os outros. ` + GBG_REF_BACKTICK + `git stash list` + GBG_REF_BACKTICK + `/` + GBG_REF_BACKTICK + `git stash show` + GBG_REF_BACKTICK + ` seguem liberados; para guardar trabalho em progresso, use uma branch própria via ` + GBG_REF_BACKTICK + `trackfw branch new` + GBG_REF_BACKTICK + ` e commit nela. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  reset-hard)
+    REASON="trackfw: git reset --hard bruto bloqueado — descarta de forma irreversível as alterações não commitadas de todo o worktree compartilhado. ` + GBG_REF_BACKTICK + `git reset --soft` + GBG_REF_BACKTICK + `/` + GBG_REF_BACKTICK + `--mixed` + GBG_REF_BACKTICK + ` seguem liberados (ex.: ` + GBG_REF_BACKTICK + `git reset --soft HEAD~1` + GBG_REF_BACKTICK + ` é o caminho padrão; use ` + GBG_REF_BACKTICK + `trackfw ship -m "..."` + GBG_REF_BACKTICK + ` para commitar e empurrar). Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  clean-force)
+    REASON="trackfw: git clean -f/-x bruto bloqueado — apaga arquivos não rastreados do worktree compartilhado, de forma irreversível. ` + GBG_REF_BACKTICK + `git clean -n` + GBG_REF_BACKTICK + `/` + GBG_REF_BACKTICK + `--dry-run` + GBG_REF_BACKTICK + ` segue liberado para revisar antes o que seria apagado. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  restore-path)
+    REASON="trackfw: git restore <path> bruto bloqueado — descarta de forma irreversível as alterações não commitadas do caminho indicado. ` + GBG_REF_BACKTICK + `git restore --staged` + GBG_REF_BACKTICK + ` (não toca o working tree) segue liberado; para descartar de fato, confirme antes com o usuário. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  checkout-path)
+    REASON="trackfw: git checkout -- <path>/git checkout . bruto bloqueado — descarta de forma irreversível as alterações não commitadas do caminho indicado. ` + GBG_REF_BACKTICK + `git checkout <branch>` + GBG_REF_BACKTICK + `/` + GBG_REF_BACKTICK + `git switch <branch>` + GBG_REF_BACKTICK + ` seguem liberados; para descartar de fato, confirme antes com o usuário. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  update-ref)
+    REASON="trackfw: git update-ref bruto bloqueado — reescreve um ref (inclusive refs/remotes/origin/*) sem tocar o objeto apontado nem exigir push, o que permite forjar o commit-alvo que ` + GBG_REF_BACKTICK + `trackfw release tag` + GBG_REF_BACKTICK + ` publicaria. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  worktree-remove-force)
+    REASON="trackfw: git worktree remove -f/--force bruto bloqueado — remove um worktree e descarta de forma irreversível qualquer alteração não commitada nele. ` + GBG_REF_BACKTICK + `git worktree remove` + GBG_REF_BACKTICK + ` sem force segue liberado (recusa sozinho quando há algo não commitado). Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  rm-force)
+    REASON="trackfw: git rm -f/--force bruto bloqueado — apaga arquivos do working tree e do index de forma irreversível, mesma classe de ` + GBG_REF_BACKTICK + `git clean -f` + GBG_REF_BACKTICK + `/` + GBG_REF_BACKTICK + `git reset --hard` + GBG_REF_BACKTICK + ` já bloqueados. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
     ;;
   *)
     exit 0
@@ -1882,15 +2446,34 @@ exit 0
 // (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' },
-  { relPath: '.codex/hooks.json', cli: 'Codex CLI' },
-  { relPath: '.gemini/settings.json', cli: 'Gemini CLI' },
-  { relPath: '.cursor/hooks.json', cli: 'Cursor' },
-  { relPath: '.copilot/settings.json', cli: 'GitHub Copilot CLI' },
-  { relPath: '.kiro/hooks/trackfw-credential-guard.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: '.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
@@ -1911,7 +2494,8 @@ function validateGuardGlobalHookResolvable(scriptMarker) {
 
   const msgs = []
   for (const gf of GLOBAL_GUARD_CONFIG_FILES) {
-    const fullPath = path.join(home, gf.relPath)
+    const relPath = globalGuardConfigPath(gf, scriptMarker)
+    const fullPath = path.join(home, relPath)
     let content
     try {
       content = fs.readFileSync(fullPath, 'utf8')
@@ -1931,23 +2515,34 @@ function validateGuardGlobalHookResolvable(scriptMarker) {
     collectCommandsWithMarker(parsed, scriptMarker, commands)
 
     const seen = new Set()
-    for (const raw of commands) {
-      if (seen.has(raw)) continue
-      seen.add(raw)
-
-      if (!path.isAbsolute(raw)) continue
+    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(raw)
+        stat = fs.statSync(m.raw)
       } catch (_) {
         stat = null
       }
 
       if (!stat) {
-        msgs.push(`~/${gf.relPath} (${gf.cli}, global scope) references ${scriptMarker} resolved to "${raw}", but the script does not exist — run \`trackfw update harness\` to regenerate it`)
+        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(`~/${gf.relPath} (${gf.cli}, global scope) references ${scriptMarker} resolved to "${raw}", but the script is not executable — run \`trackfw update harness\` to regenerate it`)
+        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`)
       }
     }
   }
@@ -1956,61 +2551,45 @@ function validateGuardGlobalHookResolvable(scriptMarker) {
 }
 
 // validateGuardGlobalScriptIntegrity is the GLOBAL-scope counterpart of
-// validateCredentialGuardScriptIntegrity/validateGitBranchGuardScriptIntegrity: for each of the 6
-// GLOBAL_GUARD_CONFIG_FILES that references scriptMarker, verifies the referenced script's content
-// matches referenceContent byte-for-byte. Port of Go's validateGuardGlobalScriptIntegrity
-// (internal/validator/validator_git_branch_guard.go) — same trigger condition and fail-open
-// contract as validateGuardGlobalHookResolvable above; does not re-validate existence/
-// executability, only content, matching the project-scope split between *_hook_resolvable and
-// *_script_integrity.
-function validateGuardGlobalScriptIntegrity(scriptMarker, referenceContent) {
+// 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 msgs = []
-  for (const gf of GLOBAL_GUARD_CONFIG_FILES) {
-    const fullPath = path.join(home, gf.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 raw of commands) {
-      if (seen.has(raw)) continue
-      seen.add(raw)
-
-      if (!path.isAbsolute(raw)) continue
-
-      let scriptContent
-      try {
-        scriptContent = fs.readFileSync(raw, 'utf8')
-      } catch (_) {
-        // Existence/readability is validateGuardGlobalHookResolvable's job — do not double-report
-        // the same underlying condition under two rule names.
-        continue
-      }
-
-      if (scriptContent === referenceContent) continue
-
-      msgs.push(`${raw} (global scope, referenced from ~/${gf.relPath}, ${gf.cli}) 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`)
-    }
+  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 []
   }
 
-  return msgs
+  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 /
@@ -2036,6 +2615,10 @@ function validateGitBranchGuardGlobalHookResolvable() {
 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
@@ -2687,6 +3270,14 @@ module.exports = {
   resolveAdrStatus,
   // ROADMAP-2026-08-12-mitigacao-do-fail-open-do-credential-guard, ML-1A
   resolveCredentialGuardHookPath,
+  // ADR-2026-08-22 (ML-1A): classificação por ancoragem
+  HOOK_ANCHORAGE_CLASS_ANCHORED,
+  HOOK_ANCHORAGE_CLASS_CWD_DEPENDENT,
+  HOOK_ANCHORAGE_CLASS_UNDECIDABLE,
+  stripOuterQuotesForClassify,
+  hookValueWasQuoted,
+  classifyHookAnchorage,
+  cwdDependentReason,
   collectCredentialGuardCommands,
   validateCredentialGuardHookResolvable,
   // ROADMAP-2026-08-12-deteccao-de-adulteracao-do-credential-guard-regra-de-validate, ML-1A