trackfw 6.8.0 → 6.9.0

package/README.md

@@ -722,6 +722,71 @@ The Codex integration is repository-scoped: `AGENTS.md` carries persistent instr
 
 ---
 
+## Credential guard: detection, not prevention
+
+trackfw can generate a **credential guard** hook that blocks agents from materializing real
+credentials. `trackfw validate` also reports when that guard looks compromised:
+
+- the hook is registered but the script is **missing** or not executable;
+- the script's **contents diverge** from the template this version of trackfw generates;
+- `credential_guard.mode` was **downgraded** from `block` on disk relative to your last commit.
+
+**Read this before relying on it.**
+
+These checks are **detection, not prevention.** trackfw *tells you* something diverged — it does
+**not** stop it from happening. This is not an implementation gap: it was measured that no technical
+prevention is possible, within trackfw's scope, against an agent that has unrestricted write access
+to your workspace. An agent that can edit your files can delete the guard script, overwrite it with
+a no-op, or relax the mode — and on most agent CLIs, a hook that fails to run simply lets the tool
+call proceed.
+
+What these checks are **not** able to see:
+
+- **changes the adversary also commits** — once it is in your `HEAD`, there is nothing to diverge
+  from. What remains is the audit trail: the change shows up in your diff and in review.
+- **anything with no commit to compare against** — a repository with no commits, or a file that was
+  never versioned. The check stays silent rather than guessing.
+- **the difference between tampering and you being out of date.** The script carries no version
+  marker, so a divergence may simply mean you have not run `trackfw update` since upgrading. That is
+  why the message is worded neutrally and the rule defaults to a **warning**, which does **not**
+  change `validate`'s exit code. If you want CI to fail on it:
+
+```yaml
+# trackfw.yaml
+rules:
+  credential_guard_script_integrity: error
+```
+
+- **the check can be switched off by the same edit it is meant to catch.** Rule severity is read
+  from `rules:` in the `trackfw.yaml` **on disk** — so an edit that both downgrades
+  `credential_guard.mode` *and* sets `credential_guard_mode_downgrade: off` silences the report,
+  with nothing committed. Anchoring `rules:` to your last commit is a known open item.
+
+### If `trackfw update` suddenly reports something it used to ignore
+
+Since the version that introduced anchoring, the credential-guard checks are resolved against **your
+last commit**, not only against the file on disk — and they can **no longer be suppressed** via
+`.trackfw-baseline.json`. This is deliberate: a check that can be switched off by the same
+uncommitted edit it is meant to catch is not a check.
+
+If one of them starts reporting after an upgrade, you have two legitimate ways out, and both leave a
+trail:
+
+```yaml
+# trackfw.yaml — commit this change
+rules:
+  credential_guard_hook_resolvable: off
+```
+
+...or fix the underlying cause (usually `trackfw update`, to regenerate the guard script and wiring).
+
+One caveat worth knowing: `governance_mode: lenient` still turns **every** finding into a warning,
+including these. Closing that is tracked separately.
+
+The strongest protection remains the ordinary one: the guard script and `trackfw.yaml` are
+**versioned files**. Review their diffs like you review any other code. Every limitation above has
+the same escape hatch: the change is *visible* in `git diff`.
+
 ## What trackfw is not
 
 - Not a project management SaaS — no accounts, no cloud sync, no data leaving your repository. A local dashboard is available via `trackfw serve`.

package/package.json

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

package/src/config/index.js

@@ -277,6 +277,28 @@ function parse(content, cfg) {
   return false;
 }
 
+// parseRulesFromContent parses only the `rules:` mapping out of arbitrary trackfw.yaml content
+// (e.g. a git-HEAD blob obtained via `git show HEAD:./trackfw.yaml`, not the CWD file load()
+// reads) and returns it as name->severity. Used by the validator's HEAD-anchored credential-guard
+// rules — see ADR-2026-08-12-severidade-das-regras-de-credential-guard-resolvida-pela-mais-estrita-
+// entre-head-e-disco.md — which need `rules:` as it existed at a specific git ref, not the CWD, so
+// they cannot go through the load() singleton (always reads the CWD file and caches it once per
+// process). Reuses parse() over an ephemeral cfg object, mirroring Go's ParseRulesFromContent, so
+// this and load() can never diverge on how `rules:` itself is read — purely additive, does not
+// touch load()/parse() otherwise. Malformed content (parse() returning true) is treated the same
+// as "no rules:" — an empty map — since the caller only wants a best-effort read of a historical
+// git blob, not a fatal exit like load() has for the live CWD file.
+function parseRulesFromContent(content) {
+  // parse() assumes cfg already has the nested-object shape defaults() provides for
+  // credentialGuard/update/sync/linkFields (it assigns into them, e.g. cfg.update.hooks = ...,
+  // never creates them) — so this cannot be a bare { rules: {} } literal or parse() throws on any
+  // content that sets one of those nested keys. rules starts empty (not seeded from defaults()),
+  // deliberately: the caller wants exactly what `rules:` in content declares, nothing else.
+  const cfg = { rules: {}, credentialGuard: {}, update: {}, sync: {}, linkFields: {} };
+  parse(content, cfg);
+  return cfg.rules;
+}
+
 const NAMESPACING_FLAT = 'flat';
 const NAMESPACING_BY_AGENT = 'by_agent';
 
@@ -285,6 +307,7 @@ module.exports = {
   reset,
   defaults,
   expandPath,
+  parseRulesFromContent,
   NAMESPACING_FLAT,
   NAMESPACING_BY_AGENT,
   MALFORMED_CONFIG_MESSAGE,

package/src/validator/git-exec.js

@@ -0,0 +1,72 @@
+'use strict'
+
+const { execFileSync } = require('child_process')
+
+// ROADMAP-2026-08-12-ancorar-rules-no-head-para-as-regras-de-credential-guard, ML-1B.
+// ADR: docs/adr/ADR-2026-08-12-severidade-das-regras-de-credential-guard-resolvida-pela-mais-
+// estrita-entre-head-e-disco.md (Emenda 3).
+//
+// Achado do ML-3B, reproduzido por Zeus: headTrackfwYAML() e isGitWorktree() (index.js) invocavam
+// execSync('git ...') sem limpar o ambiente herdado do processo — GIT_DIR/GIT_WORK_TREE
+// redirecionados para outro repositório git (sem trackfw.yaml versionado) faziam a resolução do
+// HEAD falhar EM SILÊNCIO, e credentialGuardRuleSeverity caía só no disco: derrota o mecanismo M4
+// inteiro sem nenhum commit e sem sequer editar trackfw.yaml. Exposição NOVA para
+// credential_guard_script_integrity e credential_guard_hook_resolvable — elas não dependiam de git
+// antes do M4.
+//
+// TODA invocação de git em npm/src/validator passa a ir por gitOutput() abaixo — nunca chamar
+// execSync/execFileSync('git', ...) diretamente em index.js.
+
+// GIT_ENV_PREFIX é o prefixo de TODA variável de ambiente que o git(1) reconhece como
+// configuração (GIT_DIR, GIT_WORK_TREE, GIT_CONFIG_*, GIT_CEILING_DIRECTORIES, etc.).
+//
+// A tentativa inicial deste ML era uma lista fechada (GIT_DIR, GIT_WORK_TREE, GIT_COMMON_DIR,
+// GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY, GIT_ALTERNATE_OBJECT_DIRECTORIES,
+// GIT_CEILING_DIRECTORIES, GIT_NAMESPACE) justificada por "variáveis que redirecionam ONDE o
+// repositório é lido". Essa justificativa estava ERRADA: o vetor real não é redirecionamento, é
+// fazer o `git` sair com status != 0 por QUALQUER motivo — toda chamada deste módulo trata falha
+// do subprocesso como "sem âncora, silêncio" (headTrackfwYAML) ou "fallback para disco"
+// (credentialGuardRuleSeverity), então qualquer variável capaz de tornar o git fatal já é um
+// bypass, redirecionando ou não. Provado com GIT_CONFIG_COUNT=abc (fora da lista fechada — injeta
+// config arbitrária via GIT_CONFIG_COUNT/GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n, e um valor
+// malformado faz `git rev-parse --is-inside-work-tree` sair com "fatal: unable to parse
+// command-line config", exit 128): a lista fechada não a cobria, e
+// `credential_guard_mode_downgrade` silenciava por inteiro (headTrackfwYAML retornava ok=false),
+// não só a severidade das outras duas regras.
+//
+// Por isso a abordagem correta é NEGATIVA por prefixo, não uma enumeração positiva: nenhuma
+// invocação deste módulo (`rev-parse`, `show`, `log`, `symbolic-ref`) depende de qualquer GIT_*
+// herdada do ambiente para funcionar corretamente — `-C dir` já ancora explicitamente o
+// repositório, então git redescobre a partir de dir como se tivesse sido iniciado lá. Contextos
+// legítimos que setam GIT_* (hooks do próprio git, `git submodule foreach`, worktrees vinculadas)
+// continuam funcionando sem essas variáveis porque a descoberta normal a partir de `-C dir` já
+// resolve o mesmo repositório.
+const GIT_ENV_PREFIX = 'GIT_'
+
+// cleanGitEnv retorna uma cópia de process.env sem nenhuma variável cujo nome comece com
+// GIT_ENV_PREFIX — usado como `env` de toda invocação de git deste módulo.
+function cleanGitEnv() {
+  const env = {}
+  for (const key of Object.keys(process.env)) {
+    if (!key.startsWith(GIT_ENV_PREFIX)) {
+      env[key] = process.env[key]
+    }
+  }
+  return env
+}
+
+// gitOutput executa `git -C dir ...args` ancorado explicitamente em dir via `-C` — nunca
+// dependendo só do cwd do processo/descoberta implícita — e com toda variável GIT_* removida
+// do ambiente herdado. Lança (mesmo comportamento de execSync) se o comando sair com status != 0.
+// dir vazio/undefined cai para process.cwd(), o mesmo comportamento que todo call site já assumia
+// implicitamente antes deste ML.
+function gitOutput(dir, args) {
+  const root = dir || process.cwd()
+  return execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: cleanGitEnv()
+  })
+}
+
+module.exports = { gitOutput, cleanGitEnv, GIT_ENV_PREFIX }

package/src/validator/index.js

@@ -2,7 +2,7 @@
 
 const fs = require('fs')
 const path = require('path')
-const { execSync } = require('child_process')
+const { gitOutput } = require('./git-exec')
 const config = require('../config')
 const { checkTraceIds } = require('./traceid')
 
@@ -138,10 +138,7 @@ function findAdrFile(basename) {
 // Retorna null em caso de erro ou se não houver commits.
 function gitLastModifiedTime(filePath) {
   try {
-    const out = execSync(`git log -1 --format=%ct -- "${filePath}"`, {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
-    }).trim()
+    const out = gitOutput('.', ['log', '-1', '--format=%ct', '--', filePath]).trim()
     if (out) return parseInt(out, 10) * 1000  // converter para ms
   } catch (_) {}
   return null
@@ -1085,11 +1082,10 @@ function branchNoMatchingRoadmapMessage(branch, candidates) {
 // wip/ ou done/ cujo slug case com a branch. Aceita done/ para permitir encerramento do roadmap na
 // própria branch, conforme a Definition of Done, sem reprovar o gate.
 function validateBranchHasWIPRoadmap() {
-  const { execSync } = require('child_process')
   let branch = process.env.TRACKFW_BRANCH || ''
   if (!branch && isGitWorktree(process.cwd())) {
     try {
-      branch = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
+      branch = gitOutput(process.cwd(), ['symbolic-ref', '--short', 'HEAD']).trim()
     } catch {
       branch = ''
     }
@@ -1152,15 +1148,428 @@ function validateNoteOrphan(cwd) {
   return msgs
 }
 
+// CREDENTIAL_GUARD_SCRIPT_MARKER é o nome do script que a regra credential_guard_hook_resolvable
+// procura dentro dos comandos de hook de projeto.
+const CREDENTIAL_GUARD_SCRIPT_MARKER = 'trackfw-credential-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.
+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' },
+]
+
+// resolveCredentialGuardHookPath resolve o valor bruto de um comando de hook (string extraída do
+// JSON) para um caminho de arquivo absoluto, usando exatamente as 3 formas de prefixo que o
+// trackfw emite hoje (docs/cli-parity.md, "Mecanismo de resolução de caminho dos hooks de
+// projeto, por CLI"):
+//   1. "$CLAUDE_PROJECT_DIR/…" / "$GEMINI_PROJECT_DIR/…" — placeholder de env var expandido em
+//      runtime pelo próprio CLI, substituído aqui pela raiz do projeto.
+//   2. '"$(git rev-parse --show-toplevel)/…"' — substituição de shell entre aspas literais
+//      (Codex). As aspas fazem parte do valor emitido e são removidas antes de resolver contra a
+//      raiz do projeto.
+//   3. Caminho relativo puro, sem prefixo nenhum (Cursor/Copilot/Kiro) — resolvido diretamente
+//      contra a raiz do projeto.
+// Qualquer valor que não bata em nenhuma das 3 formas retorna null — o chamador NÃO deve tratar
+// isso como violação. Não é função desta regra adivinhar wiring próprio do usuário fora dos
+// formatos que o trackfw gera.
+function resolveCredentialGuardHookPath(raw, root) {
+  const claudePrefix = '$CLAUDE_PROJECT_DIR/'
+  const geminiPrefix = '$GEMINI_PROJECT_DIR/'
+  const codexPrefix = '"$(git rev-parse --show-toplevel)/'
+
+  if (raw.startsWith(claudePrefix)) {
+    return path.join(root, raw.slice(claudePrefix.length))
+  }
+  if (raw.startsWith(geminiPrefix)) {
+    return path.join(root, raw.slice(geminiPrefix.length))
+  }
+  if (raw.startsWith(codexPrefix) && raw.endsWith('"')) {
+    const inner = raw.slice(codexPrefix.length, raw.length - 1)
+    return path.join(root, inner)
+  }
+  if (!raw.startsWith('$') && !raw.startsWith('"') && !path.isAbsolute(raw)) {
+    // Caminho relativo puro — Cursor (beforeShellExecution/preToolUse), GitHub Copilot CLI
+    // (campo "bash"), Kiro (action.command).
+    return path.join(root, raw)
+  }
+  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.
+//
+// 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) {
+  if (typeof value === 'string') {
+    if (value.includes(CREDENTIAL_GUARD_SCRIPT_MARKER)) out.push(value)
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectCredentialGuardCommands(item, out)
+    return
+  }
+  if (value && typeof value === 'object') {
+    for (const key of Object.keys(value)) collectCredentialGuardCommands(value[key], 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.
+//
+// Riscos de regressão mapeados no roadmap:
+//   - A regra só avalia entradas que EXISTEM. Ausência de entrada de guard é estado legítimo
+//     (guard global instalado via `trackfw update harness`) — nunca é violação por si só.
+//   - 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) {
+  const root = cwd || process.cwd()
+  const msgs = []
+
+  for (const hf of CREDENTIAL_GUARD_HOOK_FILES) {
+    const fullPath = path.join(root, hf.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 = []
+    collectCredentialGuardCommands(parsed, commands)
+
+    const seen = new Set()
+    for (const raw of commands) {
+      if (seen.has(raw)) continue
+      seen.add(raw)
+
+      const resolved = resolveCredentialGuardHookPath(raw, root)
+      if (resolved === null) continue
+
+      let stat = null
+      try {
+        stat = fs.statSync(resolved)
+      } catch (_) {
+        stat = null
+      }
+
+      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`)
+      } 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`)
+      }
+    }
+  }
+
+  return msgs
+}
+
 function isGitWorktree(dir) {
   try {
-    const out = execSync('git rev-parse --is-inside-work-tree', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], cwd: dir })
+    const out = gitOutput(dir, ['rev-parse', '--is-inside-work-tree'])
     return String(out).trim() === 'true'
   } catch {
     return false
   }
 }
 
+// ROADMAP-2026-08-12-deteccao-de-adulteracao-do-credential-guard-regra-de-validate, ML-1A.
+// ADR: docs/adr/ADR-2026-08-12-nao-ha-prevencao-contra-agente-induzido-com-escrita-irrestrita-a-
+// resposta-e-deteccao-ancorada-no-git.md (Emenda 1: âncora POR ALVO, decidida na Barreira B0).
+// Ver internal/validator/validator_credential_guard_integrity.go para o raciocínio completo
+// (âncoras, severidades, e por que "trackfw.yaml sem a chave" é lido como HEAD sem a chave, não
+// disco sem a chave) — replicado aqui byte-a-byte na semântica, não na forma.
+
+// CREDENTIAL_GUARD_SCRIPT_REFERENCE is a validator-local copy of the same template composed in
+// generators/hooks.js (CREDENTIAL_GUARD_SCRIPT = CG_HEADER + CG_PROJECT_GUARD + CG_DETECTION_CORE
+// + CG_PROJECT_TAIL). Not required directly from generators/hooks.js because
+// generateCredentialGuardScript() writes to disk AND console.log()s a success line on every call
+// -- calling it from inside `trackfw validate` would leak a stray "  \u2713
+// scripts/trackfw-credential-guard.sh" line into validate's output on every run, corrupting the
+// exact success message Cenario 29 fixes byte-for-byte. Kept as a literal copy (same choice made
+// in internal/validator/validator_credential_guard_integrity_reference.go for Go, for the same
+// reason) instead -- drift is caught by test/validator-credential-guard-script-reference.test.js,
+// which regenerates the real script via generateCredentialGuardScript() into a temp dir and
+// asserts byte-equality against this constant.
+const CREDENTIAL_GUARD_SCRIPT_REFERENCE = `#!/usr/bin/env bash
+# trackfw credential guard — PreToolUse/PostToolUse hook
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Script is intentionally a no-op when executed outside the project root
+[ -f "trackfw.yaml" ] || exit 0
+
+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="warn"
+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=$(grep '^roadmap_dir:' trackfw.yaml 2>/dev/null | head -1 | sed 's/^roadmap_dir:[[:space:]]*//; s/[[:space:]]*#.*$//' | tr -d '"' | tr -d "'" || true)
+ROADMAP_DIR=\${ROADMAP_DIR:-docs/roadmaps}
+
+case "$ROADMAP_DIR" in
+  /*|../*|*/../*|*/..|..) ROADMAP_DIR="docs/roadmaps" ;;
+esac
+
+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
+`
+
+// validateCredentialGuardScriptIntegrity é a regra "credential_guard_script_integrity": compara
+// scripts/trackfw-credential-guard.sh em disco contra o template que esta versão do trackfw
+// geraria. Silenciosa quando o script não existe — ausência é escopo de
+// credential_guard_hook_resolvable, não desta regra.
+function validateCredentialGuardScriptIntegrity(cwd) {
+  const root = cwd || process.cwd()
+  const relPath = 'scripts/trackfw-credential-guard.sh'
+  let content
+  try {
+    content = fs.readFileSync(path.join(root, relPath), 'utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT') return []
+    return [inspectionDiagnostic('credential_guard_script_integrity', relPath, e)]
+  }
+
+  if (content === CREDENTIAL_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_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.
+const CREDENTIAL_GUARD_MODE_LOOKBEHIND_LINES = 5
+
+// extractCredentialGuardMode replica a leitura leve (grep/sed) que o próprio script faz —
+// deliberadamente não um parser YAML completo, para que a noção desta regra de "para o que
+// credential_guard.mode resolve" bata com o que roda de fato no hook.
+function extractCredentialGuardMode(content) {
+  const lines = content.split('\n')
+  const start = lines.findIndex(l => l.startsWith('credential_guard:'))
+  if (start === -1) return { mode: '', ok: false }
+
+  const end = Math.min(start + 1 + CREDENTIAL_GUARD_MODE_LOOKBEHIND_LINES, lines.length)
+  for (const line of lines.slice(start, end)) {
+    const trimmed = line.trim()
+    if (!trimmed.includes('mode:')) continue
+    let rest = trimmed.startsWith('mode:') ? trimmed.slice('mode:'.length) : trimmed
+    rest = rest.trim()
+    const hashIdx = rest.indexOf('#')
+    if (hashIdx >= 0) rest = rest.slice(0, hashIdx).trim()
+    rest = rest.replace(/^["']+|["']+$/g, '')
+    return { mode: rest, ok: true }
+  }
+  return { mode: '', ok: false }
+}
+
+// headTrackfwYAML retorna o conteúdo de trackfw.yaml no HEAD do git, resolvido relativo a cwd
+// (não necessariamente a raiz do repo — `trackfw validate` pode rodar de um subdiretório). ok é
+// false sempre que não há âncora usável: não é worktree git, sem commits, ou trackfw.yaml não
+// versionado no HEAD — todos "sem âncora, silêncio", nunca erro.
+function headTrackfwYAML(cwd) {
+  const root = cwd || process.cwd()
+  if (!isGitWorktree(root)) return { content: '', ok: false }
+  try {
+    gitOutput(root, ['rev-parse', '--verify', 'HEAD'])
+  } catch {
+    return { content: '', ok: false }
+  }
+  try {
+    const out = gitOutput(root, ['show', 'HEAD:./trackfw.yaml'])
+    return { content: out, ok: true }
+  } catch {
+    return { content: '', ok: false }
+  }
+}
+
+// validateCredentialGuardModeDowngrade é a regra "credential_guard_mode_downgrade": dispara apenas
+// quando credential_guard.mode era explicitamente "block" no HEAD e o trackfw.yaml atual em disco
+// não resolve mais para "block" (warn explícito, valor não reconhecido, ou chave/arquivo
+// ausente — todos os quais o próprio script resolveria como "warn", o DEFAULT_MODE da variante de
+// projeto).
+//
+// Silenciosa sempre que HEAD não é "block": isso é "sem âncora para detectar downgrade", não
+// "nada errado". A ausência da chave em DISCO nunca é tratada como silêncio — é exatamente a via
+// que esta regra existe para cobrir.
+function validateCredentialGuardModeDowngrade(cwd) {
+  const root = cwd || process.cwd()
+  const head = headTrackfwYAML(root)
+  if (!head.ok) return []
+
+  const headMode = extractCredentialGuardMode(head.content)
+  if (headMode.mode !== 'block') return []
+
+  let diskContent
+  try {
+    diskContent = fs.readFileSync(path.join(root, 'trackfw.yaml'), 'utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT') return [credentialGuardModeDowngradeMessage()]
+    return [inspectionDiagnostic('credential_guard_mode_downgrade', 'trackfw.yaml', e)]
+  }
+
+  const diskMode = extractCredentialGuardMode(diskContent)
+  if (diskMode.mode === 'block') return []
+
+  return [credentialGuardModeDowngradeMessage()]
+}
+
+function credentialGuardModeDowngradeMessage() {
+  return 'trackfw.yaml sets credential_guard.mode: block at the git HEAD commit, but the ' +
+    'current file does not resolve to block — if this was intentional, commit the change; ' +
+    'otherwise investigate before treating the credential guard as active'
+}
+
 // _itemMeta: mapa de message → { rule, file } para enriquecer saída JSON.
 // Populado em applyRule e nos pushs diretos do validateUnfiltered.
 // Permanece em memória apenas durante a execução de uma chamada validate*.
@@ -1185,11 +1594,87 @@ function resetMeta() {
 // RULE_DEFAULTS mapeia regras cujo default NÃO é 'error'.
 const RULE_DEFAULTS = {
   note_orphan: 'warning',
+  // ROADMAP-2026-08-12-deteccao-de-adulteracao-do-credential-guard-regra-de-validate, ML-1A,
+  // ADR-2026-08-12 Emenda 3: the script carries no version marker, so this rule cannot tell
+  // legitimate drift (trackfw not updated yet) from tampering — kept a warning, never an error.
+  // credential_guard_mode_downgrade is deliberately absent: it falls through to ruleSeverity's
+  // 'error' default.
+  credential_guard_script_integrity: 'warning',
+}
+
+// ROADMAP-2026-08-12-ancorar-rules-no-head-para-as-regras-de-credential-guard, ML-1A.
+// ADR: docs/adr/ADR-2026-08-12-severidade-das-regras-de-credential-guard-resolvida-pela-mais-
+// estrita-entre-head-e-disco.md.
+//
+// As 3 regras abaixo resolvem severidade de forma DIFERENTE de todas as outras ~38: comparam HEAD
+// contra disco e adotam a MAIS ESTRITA das duas, em vez de ler só o disco. Deliberado, não bug —
+// sem isso, estas 3 regras podem ser desligadas pela mesma edição NÃO COMMITADA que elas deveriam
+// denunciar (`rules: credential_guard_mode_downgrade: off` em trackfw.yaml, nunca commitado). Toda
+// outra regra continua passando por diskRuleSeverity, byte-idêntico a antes deste ADR.
+const CREDENTIAL_GUARD_ANCHORED_RULES = new Set([
+  'credential_guard_hook_resolvable',
+  'credential_guard_script_integrity',
+  'credential_guard_mode_downgrade',
+])
+
+// credentialGuardSeverityRank ordena severidades da menos para a mais estrita, para a comparação
+// "mais estrita vence" de credentialGuardRuleSeverity. Qualquer valor fora de 'off'/'warning' só
+// significa 'error' na prática — applyRule já trata qualquer valor não reconhecido como violation,
+// então este ranking espelha esse mesmo fallback em vez de introduzir um contrato mais rígido.
+function credentialGuardSeverityRank(s) {
+  if (s === 'off') return 0
+  if (s === 'warning') return 1
+  return 2
+}
+
+// credentialGuardStricterSeverity retorna a mais estrita entre a e b ('error' > 'warning' > 'off').
+function credentialGuardStricterSeverity(a, b) {
+  return credentialGuardSeverityRank(a) >= credentialGuardSeverityRank(b) ? a : b
+}
+
+// credentialGuardDefaultSeverity é o mesmo fallback "RULE_DEFAULTS > error" que diskRuleSeverity
+// usa quando trackfw.yaml não tem rules: <name> — extraído para credentialGuardRuleSeverity poder
+// aplicá-lo igualmente ao lado HEAD (que não tem equivalente de RULE_DEFAULTS próprio, já que
+// config.parseRulesFromContent só devolve o que rules: em si contém).
+function credentialGuardDefaultSeverity(name) {
+  return RULE_DEFAULTS[name] || 'error'
+}
+
+// credentialGuardRuleSeverity resolve a severidade de uma das 3 CREDENTIAL_GUARD_ANCHORED_RULES
+// como a MAIS ESTRITA entre HEAD e disco — direcional, não "ignora disco e usa só HEAD" (ver o
+// parecer §2 e o ADR — o caso comum, HEAD sem menção à regra, precisa resolver para o default, ou
+// seja o valor mais estrito possível, senão o disco venceria de volta silenciosamente sempre).
+//
+// Sem HEAD (não é git worktree, sem commits, ou trackfw.yaml não versionado no HEAD —
+// headTrackfwYAML's 3 casos de "sem âncora"): cai no disco puro, igual a qualquer outra regra.
+// ADR ponto de decisão 4: limite aceito, não um bypass acionável por adversário — nenhum desses 3
+// casos é alcançável por uma edição não commitada de trackfw.yaml sozinha.
+function credentialGuardRuleSeverity(name) {
+  const diskSeverity = diskRuleSeverity(name)
+
+  const head = headTrackfwYAML()
+  if (!head.ok) return diskSeverity
+
+  const headRules = config.parseRulesFromContent(head.content)
+  const headSeverity = headRules[name] || credentialGuardDefaultSeverity(name)
+
+  return credentialGuardStricterSeverity(headSeverity, diskSeverity)
 }
 
 // ruleSeverity retorna a severidade configurada para uma regra ('error'|'warning'|'off').
 // Prioridade: trackfw.yaml rules: > RULE_DEFAULTS > 'error'.
+//
+// Para as 3 CREDENTIAL_GUARD_ANCHORED_RULES, delega a credentialGuardRuleSeverity acima — ver o
+// comentário logo antes dessa constante para o porquê. Toda outra regra segue para
+// diskRuleSeverity, textualmente idêntico ao corpo desta função antes do ADR-2026-08-12.
 function ruleSeverity(name) {
+  if (CREDENTIAL_GUARD_ANCHORED_RULES.has(name)) return credentialGuardRuleSeverity(name)
+  return diskRuleSeverity(name)
+}
+
+// diskRuleSeverity é a resolução ordinária, só-disco, usada por toda regra exceto as 3
+// CREDENTIAL_GUARD_ANCHORED_RULES: trackfw.yaml rules: (CWD) > RULE_DEFAULTS > 'error'.
+function diskRuleSeverity(name) {
   const cfg = config.load()
   if (cfg.rules[name]) return cfg.rules[name]
   if (RULE_DEFAULTS[name]) return RULE_DEFAULTS[name]
@@ -1255,6 +1740,9 @@ 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_mode_downgrade', validateCredentialGuardModeDowngrade(), violations, warnings)
 
   // Regras configuráveis via applyRule (popula _itemMeta automaticamente)
   applyRule('req_has_adr',          validateREQsHaveADR(),          violations, warnings)
@@ -1288,6 +1776,16 @@ async function validateUnfiltered() {
 
 // validate executa todas as validações, aplica ratchet (baseline) e modo lenient.
 // Retorna { violations, warnings }.
+//
+// ADR-2026-08-12-severidade-das-regras-de-credential-guard-resolvida-pela-mais-estrita-entre-head-
+// e-disco: carve-out do baseline — violations/warnings de uma das 3
+// CREDENTIAL_GUARD_ANCHORED_RULES NUNCA são toleradas via .trackfw-baseline.json, não importa o
+// que o arquivo contenha para elas. Mecanismo DIFERENTE do HEAD-vs-disco em
+// credentialGuardRuleSeverity: .trackfw-baseline.json é .gitignore'd DE PROPÓSITO ("baseline local
+// de violations toleradas (nao versionado)"), então não há HEAD desse arquivo para comparar —
+// "exigir commit" simplesmente não se aplica a um arquivo que o projeto decidiu nunca versionar. A
+// única forma de fechar esse canal é excluir estas 3 regras da elegibilidade de ratchet, por nome,
+// independente do conteúdo da mensagem — daí a checagem via getItemMeta(msg).rule abaixo.
 async function validate() {
   const result = await validateUnfiltered()
   let { violations, warnings } = result
@@ -1296,9 +1794,9 @@ async function validate() {
   const baseline = loadBaseline()
   if (baseline) {
     const baselineSet = new Set(baseline.violations || [])
-    violations = violations.filter(v => !baselineSet.has(v))
+    violations = violations.filter(v => !baselineSet.has(v) || CREDENTIAL_GUARD_ANCHORED_RULES.has(getItemMeta(v).rule))
     const baselineWarnSet = new Set(baseline.warnings || [])
-    warnings = warnings.filter(w => !baselineWarnSet.has(w))
+    warnings = warnings.filter(w => !baselineWarnSet.has(w) || CREDENTIAL_GUARD_ANCHORED_RULES.has(getItemMeta(w).rule))
   }
 
   // Modo lenient: mover violations para warnings, exit code 0
@@ -1505,4 +2003,13 @@ module.exports = {
   // ML-1D (2026-08-01 — reconciliação de paridade: frontmatter-first)
   extractFrontmatterField,
   resolveAdrStatus,
+  // ROADMAP-2026-08-12-mitigacao-do-fail-open-do-credential-guard, ML-1A
+  resolveCredentialGuardHookPath,
+  collectCredentialGuardCommands,
+  validateCredentialGuardHookResolvable,
+  // ROADMAP-2026-08-12-deteccao-de-adulteracao-do-credential-guard-regra-de-validate, ML-1A
+  validateCredentialGuardScriptIntegrity,
+  validateCredentialGuardModeDowngrade,
+  extractCredentialGuardMode,
+  CREDENTIAL_GUARD_SCRIPT_REFERENCE,
 }