trackfw 7.0.0 → 7.1.0

package/src/generators/hooks.js

@@ -472,15 +472,63 @@ const GLOBAL_CREDENTIAL_GUARD_SCRIPT = CG_HEADER + CG_DETECTION_CORE + CG_GLOBAL
 const GBG_BACKTICK = '\\`'
 
 const GIT_BRANCH_GUARD_SCRIPT = `#!/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
     \\{*)
@@ -513,15 +561,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
@@ -529,6 +705,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
 
@@ -562,9 +761,80 @@ match_subcommand() {
         return 0
         ;;
       checkout)
-        if [ "\${1:-}" = "-b" ]; then
-          echo "checkout-b"
-          return 0
+        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
@@ -580,6 +850,15 @@ case "$SUBCOMMAND" in
   checkout-b)
     REASON="trackfw: git checkout -b bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_BACKTICK + `. Ver CLAUDE.md §1."
     ;;
+  switch-c)
+    REASON="trackfw: git switch -c bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_BACKTICK + `. Ver CLAUDE.md §1."
+    ;;
+  branch-create)
+    REASON="trackfw: git branch bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_BACKTICK + `. Ver CLAUDE.md §1."
+    ;;
+  worktree-add-b)
+    REASON="trackfw: git worktree add -b bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_BACKTICK + `. Ver CLAUDE.md §1."
+    ;;
   commit)
     REASON="trackfw: git commit bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw commit -m '<mensagem>'` + GBG_BACKTICK + `. Ver CLAUDE.md §1."
     ;;
@@ -832,17 +1111,95 @@ function readGlobalHookJSON(...relParts) {
   }
 }
 
-/** Read-only counterpart of mergeClaudeHookArray. */
+/**
+ * Collapses runs of consecutive slashes ("//" -> "/", any position,
+ * including leading) and strips a trailing slash, so two on-disk forms of
+ * the SAME script path compare equal regardless of incidental formatting
+ * (e.g. $HOME resolving with a trailing slash, as happens with macOS's
+ * $TMPDIR, or a hand-edited config file). Does NOT resolve "." / ".."
+ * segments or symlinks -- those transforms would let unrelated paths
+ * compare equal (silently disarming the dedup, the more dangerous failure
+ * mode here) and symlink resolution errors on a path that does not exist
+ * yet, which every caller here must fail OPEN on. Hand-rolled instead of
+ * path.normalize because it disagrees with Go's filepath.Clean and Python's
+ * os.path.normpath on leading "//" and trailing "/" handling (measured) --
+ * mirrored byte-for-byte in internal/generators/agentfiles.go
+ * (normalizeGuardPath) and pypi/trackfw/generators/hooks.py
+ * (_normalize_guard_path). Never call with anything other than a script
+ * path -- it is not a general string normalizer.
+ */
+function normalizeGuardPath(p) {
+  if (!p) return p
+  let out = ''
+  let prevSlash = false
+  for (const ch of p) {
+    if (ch === '/') {
+      if (prevSlash) continue
+      prevSlash = true
+    } else {
+      prevSlash = false
+    }
+    out += ch
+  }
+  if (out.length > 1 && out.endsWith('/')) {
+    out = out.replace(/\/+$/, '') || '/'
+  }
+  return out
+}
+
+/** Reports whether a and b denote the same script command path after normalizeGuardPath. */
+function samePathCommand(a, b) {
+  return normalizeGuardPath(a) === normalizeGuardPath(b)
+}
+
+/**
+ * Read-only counterpart of mergeClaudeHookArray. Compares command paths via
+ * samePathCommand (normalized), not raw string equality.
+ *
+ * ROADMAP-2026-08-17 ML-4B: also requires the sibling `type` field to equal
+ * "command" -- mergeClaudeHookArray always writes
+ * {type:'command',command:...}, and Claude/Codex/Gemini all silently ignore
+ * a hook entry missing "type":"command" (measured, hades-tf ML-4A barrier
+ * finding: a global entry with the correct command but no `type` field
+ * looked "installed" to the dedup, so the project-scope entry was skipped
+ * in favor of a global entry that never actually executes -- leaving BOTH
+ * scopes silently unprotected while `trackfw validate` stayed green).
+ * Requiring "type":"command" here closes that gap: a malformed global entry
+ * is now treated as "not installed", so the project-scope entry gets
+ * re-wired instead of being skipped.
+ */
 function hookArrayHasCommand(existing, matcher, command) {
   const arr = Array.isArray(existing) ? existing : []
   for (const item of arr) {
     if (!item || item.matcher !== matcher) continue
     const inner = Array.isArray(item.hooks) ? item.hooks : []
-    if (inner.some(h => h && h.command === command)) return true
+    if (inner.some(h => h && h.type === 'command' && typeof h.command === 'string' && samePathCommand(h.command, command))) return true
   }
   return false
 }
 
+/**
+ * Read-only, path-normalized counterpart of hasEntry -- used ONLY by the
+ * global-dedup read paths (globalXInstalledCursor/Copilot below), never by
+ * the write-side merge/idempotency helpers (mergeSimpleCommandArray,
+ * injectCursorHooks), which must keep comparing raw strings so their
+ * idempotency behavior does not drift from Go/Python. See samePathCommand's
+ * doc comment for why the value must always be a script path.
+ *
+ * ROADMAP-2026-08-17 ML-4B: requireCommandType mirrors Go's
+ * simpleArrayHasValue -- Copilot entries (mergeCredentialGuardCopilotHooks)
+ * always carry "type":"command" and Copilot ignores an entry without it
+ * (same hades-tf ML-4A finding as hookArrayHasCommand above), so Copilot
+ * callers pass true. Cursor entries (mergeCredentialGuardCursorHooks,
+ * {command:...}) never carry a `type` field -- not part of Cursor's schema
+ * -- so requiring it there would make this always return false for a
+ * perfectly valid, executing Cursor entry; Cursor callers pass false. Do
+ * NOT uniformize this across CLIs.
+ */
+function hasEntryPath(arr, field, value, requireCommandType) {
+  return Array.isArray(arr) && arr.some(e => e && (!requireCommandType || e.type === 'command') && typeof e[field] === 'string' && samePathCommand(e[field], value))
+}
+
 function globalCredentialGuardInstalledClaude() {
   const scriptPath = globalCredentialGuardScriptPath()
   if (!scriptPath) return false
@@ -872,7 +1229,7 @@ function globalCredentialGuardInstalledCursor() {
   if (!scriptPath) return false
   const root = readGlobalHookJSON('.cursor', 'hooks.json')
   if (!root || !root.hooks) return false
-  return hasEntry(root.hooks.beforeShellExecution, 'command', scriptPath)
+  return hasEntryPath(root.hooks.beforeShellExecution, 'command', scriptPath, false)
 }
 
 function globalCredentialGuardInstalledCopilot() {
@@ -880,7 +1237,7 @@ function globalCredentialGuardInstalledCopilot() {
   if (!scriptPath) return false
   const root = readGlobalHookJSON('.copilot', 'settings.json')
   if (!root || !root.hooks) return false
-  return hasEntry(root.hooks.preToolUse, 'bash', scriptPath)
+  return hasEntryPath(root.hooks.preToolUse, 'bash', scriptPath, true)
 }
 
 /**
@@ -900,6 +1257,68 @@ function globalCredentialGuardInstalledKiro() {
   }
 }
 
+// ---------------------------------------------------------------------------
+// git-branch-guard global-installed dedup (ROADMAP-2026-08-17 Wave 2/ML-2B)
+//
+// Mirrors the globalCredentialGuardInstalled<Tool> family above exactly,
+// pointed at ~/.trackfw/scripts/trackfw-git-branch-guard.sh instead of
+// trackfw-credential-guard.sh. Only 5 of the 6 credential-guard dedup
+// targets have a git-branch-guard counterpart: Kiro's project-scope
+// injector never wires git-branch-guard at all (see injectKiroHooks'
+// git-branch-guard doc comment), so there is no
+// globalGitBranchGuardInstalledKiro. Windsurf/AmazonQ wire git-branch-guard
+// at project scope but have no global-scope target (ML-2A only added
+// targets for the 6 CLIs credential-guard already covers) and no
+// credential-guard dedup precedent either -- consistent, not a gap.
+// ---------------------------------------------------------------------------
+
+/** Mirrors Go's globalGitBranchGuardScriptPath. */
+function globalGitBranchGuardScriptPath() {
+  const home = os.homedir()
+  if (!home) return null
+  return path.join(home, '.trackfw', 'scripts', 'trackfw-git-branch-guard.sh')
+}
+
+function globalGitBranchGuardInstalledClaude() {
+  const scriptPath = globalGitBranchGuardScriptPath()
+  if (!scriptPath) return false
+  const root = readGlobalHookJSON('.claude', 'settings.json')
+  if (!root || !root.hooks) return false
+  return hookArrayHasCommand(root.hooks.PreToolUse, 'Bash', scriptPath)
+}
+
+function globalGitBranchGuardInstalledCodex() {
+  const scriptPath = globalGitBranchGuardScriptPath()
+  if (!scriptPath) return false
+  const root = readGlobalHookJSON('.codex', 'hooks.json')
+  if (!root || !root.hooks) return false
+  return hookArrayHasCommand(root.hooks.PreToolUse, 'Bash', scriptPath)
+}
+
+function globalGitBranchGuardInstalledGemini() {
+  const scriptPath = globalGitBranchGuardScriptPath()
+  if (!scriptPath) return false
+  const root = readGlobalHookJSON('.gemini', 'settings.json')
+  if (!root || !root.hooks) return false
+  return hookArrayHasCommand(root.hooks.BeforeTool, 'run_shell_command', scriptPath)
+}
+
+function globalGitBranchGuardInstalledCursor() {
+  const scriptPath = globalGitBranchGuardScriptPath()
+  if (!scriptPath) return false
+  const root = readGlobalHookJSON('.cursor', 'hooks.json')
+  if (!root || !root.hooks) return false
+  return hasEntryPath(root.hooks.beforeShellExecution, 'command', scriptPath, false)
+}
+
+function globalGitBranchGuardInstalledCopilot() {
+  const scriptPath = globalGitBranchGuardScriptPath()
+  if (!scriptPath) return false
+  const root = readGlobalHookJSON('.copilot', 'settings.json')
+  if (!root || !root.hooks) return false
+  return hasEntryPath(root.hooks.preToolUse, 'bash', scriptPath, true)
+}
+
 // ---------------------------------------------------------------------------
 // generateAttentionScripts — writes the two shell scripts to scripts/
 // ---------------------------------------------------------------------------
@@ -966,11 +1385,13 @@ function injectClaudeHooks(cwd) {
   }
 
   // git branch guard (ROADMAP-2026-08-14, ML-3B/Wave 3, step 1): PreToolUse-only, matcher
-  // "Bash" — blocks raw `git commit`/`git push`/`git checkout -b` before they execute. No
-  // global-install dedup here (unlike GUARD_CMD_CLAUDE above): there is no per-CLI global
-  // git-branch-guard harness target yet (only the plain script-generation call at
-  // GenerateGlobalGitBranchGuardScript/generateGlobalGitBranchGuardScript exists so far).
-  data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Bash', GBG_CMD_CLAUDE)
+  // "Bash" — blocks raw `git commit`/`git push`/`git checkout -b` before they execute.
+  // Dedup (ROADMAP-2026-08-17 Wave 2/ML-2B): skip the project-scope entry when the global
+  // one is already installed (`trackfw update harness --targets claude-git-branch-guard`),
+  // so the guard doesn't fire (and print its block message) twice per Bash call.
+  if (!globalGitBranchGuardInstalledClaude()) {
+    data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Bash', GBG_CMD_CLAUDE)
+  }
 
   writeJSON(filePath, data)
 }
@@ -1026,9 +1447,12 @@ function injectCodexHooks(cwd) {
   }
 
   // git branch guard (ROADMAP-2026-08-14, ML-3B/Wave 3, step 2): PreToolUse-only, matcher
-  // "Bash" -- git commands only ever run via the Bash tool, never apply_patch. No
-  // global-install dedup (see GBG_CMD_CLAUDE comment).
-  data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Bash', GBG_CMD_CODEX)
+  // "Bash" -- git commands only ever run via the Bash tool, never apply_patch.
+  // Dedup (ROADMAP-2026-08-17 Wave 2/ML-2B): skip project-scope when the global one is
+  // already installed (`trackfw update harness --targets codex-git-branch-guard`).
+  if (!globalGitBranchGuardInstalledCodex()) {
+    data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Bash', GBG_CMD_CODEX)
+  }
 
   writeJSON(filePath, data)
 }
@@ -1097,9 +1521,12 @@ function injectGeminiHooks(cwd) {
   }
 
   // git branch guard (ROADMAP-2026-08-14, ML-3B/Wave 3, step 3): BeforeTool-only, matcher
-  // "run_shell_command" -- git commands only ever run via the shell tool. No global-install
-  // dedup (see GBG_CMD_CLAUDE comment).
-  data.hooks.BeforeTool = mergeClaudeHookArray(data.hooks.BeforeTool, 'run_shell_command', GBG_CMD_GEMINI)
+  // "run_shell_command" -- git commands only ever run via the shell tool.
+  // Dedup (ROADMAP-2026-08-17 Wave 2/ML-2B): skip project-scope when the global one is
+  // already installed (`trackfw update harness --targets gemini-git-branch-guard`).
+  if (!globalGitBranchGuardInstalledGemini()) {
+    data.hooks.BeforeTool = mergeClaudeHookArray(data.hooks.BeforeTool, 'run_shell_command', GBG_CMD_GEMINI)
+  }
 
   writeJSON(filePath, data)
 }
@@ -1259,9 +1686,14 @@ function injectCopilotHooks(cwd) {
   // Go's InjectCopilotHooks (internal/generators/agentfiles.go), which made the same
   // choice for the same reason; the CLI-flag/permissions-config.json approach is a
   // documented, deliberate divergence from the roadmap's literal wording. This file is
-  // overwritten wholesale every run, so no dedup-against-global check is needed --
-  // added unconditionally, matching the always-on attention-signal/cleanup entries.
-  preToolUse.push({ type: 'command', matcher: 'bash', bash: GBG_CMD_COPILOT, cwd: '.', timeoutSec: 10 })
+  // overwritten wholesale every run, but that only means there is no migration concern
+  // -- it does not exempt this entry from the dedup-against-global check
+  // (ROADMAP-2026-08-17 Wave 2/ML-2B): skip project-scope when the global one is
+  // already installed (`trackfw update harness --targets copilot-git-branch-guard`),
+  // same reasoning as the credential-guard dedup above.
+  if (!globalGitBranchGuardInstalledCopilot()) {
+    preToolUse.push({ type: 'command', matcher: 'bash', bash: GBG_CMD_COPILOT, cwd: '.', timeoutSec: 10 })
+  }
 
   const data = {
     version: 1,
@@ -1396,11 +1828,19 @@ function injectCursorHooks(cwd) {
   }
 
   // git branch guard (ROADMAP-2026-08-14, ML-3B/Wave 3, step 5): beforeShellExecution-only --
-  // Cursor's dedicated pre-execution Bash event; git commands only ever run there. No
-  // global-install dedup (see GBG_CMD_CLAUDE comment).
-  if (!Array.isArray(data.hooks.beforeShellExecution)) data.hooks.beforeShellExecution = []
-  if (!hasEntry(data.hooks.beforeShellExecution, 'command', GBG_CMD_CURSOR)) {
-    data.hooks.beforeShellExecution.push({ command: GBG_CMD_CURSOR })
+  // Cursor's dedicated pre-execution Bash event; git commands only ever run there.
+  // Dedup (ROADMAP-2026-08-17 Wave 2/ML-2B): skip project-scope when the global one is
+  // already installed (`trackfw update harness --targets cursor-git-branch-guard`). The
+  // key is intentionally only touched inside this conditional (never created outside it)
+  // so that when BOTH credential-guard and git-branch-guard are deduped away, the key
+  // stays absent from the emitted JSON rather than becoming a present-but-empty array --
+  // matches Go's InjectCursorHooks, which check-agent-hooks-parity.sh's structural
+  // comparator treats as significant (absent key vs empty array is drift, not noise).
+  if (!globalGitBranchGuardInstalledCursor()) {
+    if (!Array.isArray(data.hooks.beforeShellExecution)) data.hooks.beforeShellExecution = []
+    if (!hasEntry(data.hooks.beforeShellExecution, 'command', GBG_CMD_CURSOR)) {
+      data.hooks.beforeShellExecution.push({ command: GBG_CMD_CURSOR })
+    }
   }
 
   writeJSON(filePath, data)
@@ -1650,4 +2090,6 @@ module.exports = {
   mergeClaudeHookArray,
   mergeSimpleCommandArray,
   mergeCopilotHookArray,
+  normalizeGuardPath,
+  samePathCommand,
 }

package/src/i18n/locales/en-US.json

@@ -120,8 +120,5 @@
     "no_data": "No transitions recorded yet.",
     "since": "Filter by period (e.g. 7d, 30d, 90d)",
     "export": "Export metrics to CSV file"
-  },
-  "errors": {
-    "notFound": "Not found: {{path}}"
   }
 }

package/src/i18n/locales/es-ES.json

@@ -120,8 +120,5 @@
     "no_data": "No hay transiciones registradas aún.",
     "since": "Filtrar por período (ej: 7d, 30d, 90d)",
     "export": "Exportar métricas a archivo CSV"
-  },
-  "errors": {
-    "notFound": "No encontrado: {{path}}"
   }
 }

package/src/i18n/locales/pt-BR.json

@@ -120,8 +120,5 @@
     "no_data": "Nenhuma transição registrada ainda.",
     "since": "Filtrar por período (ex: 7d, 30d, 90d)",
     "export": "Exportar métricas para arquivo CSV"
-  },
-  "errors": {
-    "notFound": "Não encontrado: {{path}}"
   }
 }