trackfw 6.5.1 → 6.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "6.5.1",
+  "version": "6.7.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/commands/adr.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const path = require('path')
+const os = require('os')
 const { Command } = require('commander')
 const { input } = require('@inquirer/prompts')
 const generators = require('../generators/adr')
@@ -8,9 +10,29 @@ const { t } = require('../i18n')
 const cmd = new Command('adr')
 cmd.description(t('adr.description'))
 
+/**
+ * Resolve o diretório de ADRs conforme --scope.
+ * 'project' (default) preserva o comportamento atual (adrDirs[0] do trackfw.yaml).
+ * 'global' escreve/lista em ~/.trackfw/adr, sem exigir trackfw.yaml no cwd.
+ * @param {string} scope
+ * @returns {string}
+ */
+function resolveAdrDir(scope) {
+  if (scope === 'global') {
+    return path.join(os.homedir(), '.trackfw', 'adr')
+  }
+  if (scope === 'project') {
+    return require('../config').load().adrDirs[0]
+  }
+  console.error(`Invalid --scope value: "${scope}". Expected "project" or "global".`)
+  process.exit(1)
+}
+
 cmd.command('new <title>')
   .description(t('adr.new.description'))
-  .action(async (title) => {
+  .option('--scope <scope>', 'ADR scope: project (default) or global (~/.trackfw/adr)', 'project')
+  .action(async (title, options) => {
+    const adrDir = resolveAdrDir(options.scope)
     const content = { title }
     // wizard interativo se TTY
     if (process.stdin.isTTY) {
@@ -19,13 +41,15 @@ cmd.command('new <title>')
       content.consequences = await input({ message: t('adr.new.prompt.consequences'), default: '' })
       content.alternatives = await input({ message: t('adr.new.prompt.alternatives'), default: '' })
     }
-    await generators.newADR(content)
+    await generators.newADR(content, adrDir)
   })
 
 cmd.command('list')
   .description(t('adr.list.description'))
-  .action(async () => {
-    await generators.listADRs(require('../config').load().adrDirs[0])
+  .option('--scope <scope>', 'ADR scope: project (default) or global (~/.trackfw/adr)', 'project')
+  .action(async (options) => {
+    const adrDir = resolveAdrDir(options.scope)
+    await generators.listADRs(adrDir)
   })
 
 module.exports = cmd

package/src/commands/req.js

@@ -1,4 +1,6 @@
 'use strict'
+const path = require('path')
+const os = require('os')
 const { Command } = require('commander')
 const { listREQs, moveREQ } = require('../generators/req')
 const { t } = require('../i18n')
@@ -26,6 +28,19 @@ cmd.command('new <title>')
       // Form 2 — critérios de aceite
       content.criteria = await input({ message: t('req.new.prompt.criteria'), default: '- [ ]\n- [ ]' })
 
+      // Escopo dos ADR drafts desta sessão (uma única pergunta, vale para todos)
+      const adrScope = await select({
+        message: t('req.new.prompt.adrScope'),
+        choices: [
+          { name: t('req.new.prompt.adrScopeLocal'), value: 'local' },
+          { name: t('req.new.prompt.adrScopeGlobal'), value: 'global' },
+        ],
+        default: 'local',
+      })
+      const adrDir = adrScope === 'global'
+        ? path.join(os.homedir(), '.trackfw', 'adr')
+        : require('../config').load().adrDirs[0]
+
       // Perguntas dinâmicas por probe
       const generatedADRs = []
       for (const probe of probes) {
@@ -40,7 +55,7 @@ cmd.command('new <title>')
           })
           if (answer) {
             try {
-              const basename = await adrGenerators.newADRDraft(answer)
+              const basename = await adrGenerators.newADRDraft(answer, adrDir)
               if (basename) generatedADRs.push(basename)
             } catch (e) {
               console.warn(t('req.new.adrWarning', { slug: answer, message: e.message }))

package/src/commands/update.js

@@ -29,6 +29,83 @@ function loadUpdateConfig(rootDir) {
   };
 }
 
+// ensureGlobalAdrDirRegistered — mirrors internal/generators/update.go's
+// ensureGlobalADRDirRegistered (Go implementation, same REQ, ML-1A). Registers
+// ~/.trackfw/adr in the project's trackfw.yaml `adr_dirs` list, but ONLY when
+// that directory exists AND contains at least one `ADR-*.md` file — an empty
+// or absent global ADR dir is a no-op, never written. The edit is surgical
+// (line-based text splice, not a YAML parse+reserialize) to preserve 100% of
+// the user's existing trackfw.yaml content (comments, key order, formatting).
+function ensureGlobalAdrDirRegistered(cwd) {
+  const home = os.homedir();
+  const globalDir = path.join(home, '.trackfw', 'adr');
+  if (!fs.existsSync(globalDir)) return;
+
+  let hasAdr = false;
+  try {
+    hasAdr = fs.readdirSync(globalDir).some((f) => /^ADR-.*\.md$/.test(f));
+  } catch (_) {
+    return;
+  }
+  if (!hasAdr) return;
+
+  const yamlPath = path.join(cwd, 'trackfw.yaml');
+  let content;
+  try {
+    content = fs.readFileSync(yamlPath, 'utf8');
+  } catch (_) {
+    return;
+  }
+
+  const resolvesToGlobal = (entry) => {
+    const trimmed = entry.trim();
+    if (trimmed === '~/.trackfw/adr') return true;
+    const expanded = trimmed.startsWith('~') ? path.join(home, trimmed.slice(1)) : trimmed;
+    return path.resolve(expanded) === path.resolve(globalDir);
+  };
+
+  const lines = content.split('\n');
+  let adrDirsIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^adr_dirs:\s*$/.test(lines[i])) {
+      adrDirsIndex = i;
+      break;
+    }
+  }
+
+  if (adrDirsIndex === -1) {
+    // No adr_dirs key at all — the implicit default is `docs/adr`; append a
+    // new block preserving that default explicitly, plus the global entry.
+    let newContent = content;
+    if (newContent.length && !newContent.endsWith('\n')) newContent += '\n';
+    newContent += 'adr_dirs:\n  - docs/adr\n  - ~/.trackfw/adr\n';
+    fs.writeFileSync(yamlPath, newContent, 'utf8');
+    console.log('  ✓ adr_dirs: ~/.trackfw/adr registrado');
+    return;
+  }
+
+  const itemRe = /^(\s*)-\s*(.+?)\s*$/;
+  let end = adrDirsIndex + 1;
+  let lastItemIndex = -1;
+  let indent = '  ';
+  while (end < lines.length) {
+    const m = lines[end].match(itemRe);
+    if (!m) break;
+    indent = m[1] || indent;
+    if (resolvesToGlobal(m[2])) {
+      // Already registered under this or an equivalent path form — no-op.
+      return;
+    }
+    lastItemIndex = end;
+    end++;
+  }
+
+  const insertAt = lastItemIndex === -1 ? adrDirsIndex + 1 : lastItemIndex + 1;
+  lines.splice(insertAt, 0, `${indent}- ~/.trackfw/adr`);
+  fs.writeFileSync(yamlPath, lines.join('\n'), 'utf8');
+  console.log('  ✓ adr_dirs: ~/.trackfw/adr registrado');
+}
+
 function updateHooksSurgical(cfg, rootDir) {
   const hooks = cfg.hooks || '';
   if (hooks === 'husky') {
@@ -243,6 +320,8 @@ cmd.action((mode, options) => {
     process.exit(1);
   }
 
+  ensureGlobalAdrDirRegistered(cwd);
+
   let wanted;
   try {
     const requested = options.targets ? String(options.targets).split(',').map((s) => s.trim()).filter(Boolean) : [];

package/src/generators/adr.js

@@ -43,13 +43,13 @@ function today() {
 }
 
 /**
- * Cria um novo ADR em docs/adr/ADR-YYYY-MM-DD-<slug>.md.
+ * Cria um novo ADR em <adrDir>/ADR-YYYY-MM-DD-<slug>.md.
  * Campos vazios recebem placeholder HTML.
  * @param {{ title: string, context?: string, decision?: string, consequences?: string, alternatives?: string }} content
+ * @param {string} adrDir Diretório de destino (resolvido pelo chamador conforme --scope)
  * @returns {Promise<void>}
  */
-async function newADR(content) {
-  const adrDir = require('../config').load().adrDirs[0]
+async function newADR(content, adrDir) {
   fs.mkdirSync(adrDir, { recursive: true })
 
   const slug = toSlug(content.title)
@@ -142,10 +142,14 @@ function parseADRStatus(filepath) {
  * Cria um ADR com Status: Draft a partir de um slug.
  * Idempotente: se já existe ADR-*-<slug>.md, pula e imprime mensagem.
  * @param {string} slug
+ * @param {string} [adrDir] Diretório de destino (resolvido pelo chamador conforme escopo).
+ *   Se omitido, preserva o comportamento anterior (adrDirs[0] do trackfw.yaml).
  * @returns {Promise<string>} basename do arquivo criado
  */
-async function newADRDraft(slug) {
-  const adrDir = require('../config').load().adrDirs[0]
+async function newADRDraft(slug, adrDir) {
+  if (!adrDir) {
+    adrDir = require('../config').load().adrDirs[0]
+  }
   fs.mkdirSync(adrDir, { recursive: true })
 
   // Verificar idempotência: buscar arquivo existente com o mesmo slug

package/src/generators/hooks.js

@@ -174,8 +174,6 @@ elif printf '%s' "$INPUT" | grep -qE "$AWS_KEY_PATTERN"; then
   MATCH="AWS access key"
 fi
 
-[ -n "$MATCH" ] || exit 0
-
 # 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
@@ -206,6 +204,57 @@ is_ephemeral_target() {
 
 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
@@ -227,10 +276,22 @@ fi
 
 `
 
-const CG_PROJECT_TAIL = `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)
+// Resolução de MODE (grep de `credential_guard.mode` em trackfw.yaml + fallback) é inlined,
+// idêntica em CG_PROJECT_TAIL (fallback "warn") e CG_GLOBAL_TAIL (fallback "block") — ao invés de
+// extrair para uma constante JS compartilhada e concatenar (como o Go faz via
+// credentialGuardModeResolution/DEFAULT_MODE), aqui o texto é replicado como literal em cada
+// template literal: o gate de paridade Go/Node/Python
+// (internal/generators/credential_guard_test.go, getNodeSourceBlock) extrai cada constante via
+// regex de um único bloco `` `const NAME = \`...\`` `` sem suportar concatenação de string —
+// concatenar quebraria a extração estática. Nunca editar a lógica de resolução em só um dos dois
+// blocos sem replicar no outro (ML-1B, ADR-2026-08-06 emenda 6). Mirrors Go's
+// credentialGuardModeResolution (semântica idêntica, forma sintática diferente por essa restrição
+// do parser de paridade).
+const CG_PROJECT_TAIL = `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="warn" ;;
+  *) MODE="$DEFAULT_MODE" ;;
 esac
 
 if [ "$MODE" = "block" ]; then
@@ -259,10 +320,42 @@ printf '{"tool":"credential-guard","message":"%s","level":"action_required","tim
 exit 0
 `
 
-// Escopo global: modo sempre "warn" (ver ADR-2026-08-06/ROADMAP-2026-08-06 Wave 1 — decisão "b",
-// sem ~/.trackfw/config.yaml) e ROADMAP_DIR fixo em "docs/roadmaps" relativo ao cwd, só grava o
-// attention signal se esse diretório já existir (não cria docs/roadmaps num projeto qualquer).
-const CG_GLOBAL_TAIL = `MODE="warn"
+// CG_GLOBAL_TAIL é a contraparte de CG_PROJECT_TAIL para o escopo global
+// (~/.trackfw/scripts/trackfw-credential-guard.sh, instalado via `trackfw update harness`).
+//
+// Decisão (ML-1B, ver ADR-2026-08-06 emenda 6 de 2026-08-08 e ROADMAP-2026-08-08, Wave 1): o modo
+// em escopo global reusa a MESMA leitura de `credential_guard.mode` de trackfw.yaml que
+// CG_PROJECT_TAIL já faz (mesma resolução, replicada aqui — ver o comentário de CG_PROJECT_TAIL
+// sobre por que não é extraída para uma constante compartilhada em Node) — sem exigir trackfw.yaml
+// existir (não há o guard `[ -f trackfw.yaml ] || exit 0` da variante de projeto: o objetivo do
+// escopo global é proteger qualquer projeto, com ou sem trackfw.yaml). Quando o hook global roda a
+// partir do cwd de um projeto com trackfw.yaml e credential_guard.mode explícito, esse valor é
+// respeitado (warn ou block) — nenhuma mudança de comportamento para quem já definiu mode: warn
+// explicitamente. Em qualquer outro caso (sem trackfw.yaml, ou trackfw.yaml sem essa chave), o
+// fallback deixa de ser "warn" e passa a ser "block": um guard opt-in que nunca bloqueia por
+// padrão é uma falsa sensação de proteção — o usuário que rodou `trackfw update harness` já
+// demonstrou intenção explícita de ter o mecanismo ativo. Supersede a decisão original ("modo
+// global sempre warn", opção "b" avaliada na ADR original) — não cria ~/.trackfw/config.yaml nem
+// nenhuma outra segunda fonte de configuração só para isto.
+//
+// ROADMAP_DIR em escopo global: como não há garantia de trackfw.yaml para ler `roadmap_dir:`, o
+// script usa o caminho padrão fixo "docs/roadmaps" relativo ao cwd de onde o hook foi disparado, e
+// só grava o attention signal se esse diretório já existir (e só em modo warn — modo block nunca
+// grava o attention signal, mesma decisão da variante de projeto). Não cria "docs/roadmaps" em um
+// projeto aleatório só para sinalizar isso — isso pareceria ao usuário que o trackfw foi
+// "instalado" nesse projeto, o que não é verdade. O texto de warning/block em stderr acontece
+// sempre (visível no output do CLI/hook), independente de o diretório de attention existir.
+const CG_GLOBAL_TAIL = `DEFAULT_MODE="block"
+MODE=$(grep -A 5 '^credential_guard:' trackfw.yaml 2>/dev/null | grep 'mode:' | head -1 | sed -E 's/^[[:space:]]*mode:[[:space:]]*//; s/[[:space:]]*#.*$//' | tr -d "\\"'" || true)
+case "$MODE" in
+  warn|block) ;;
+  *) MODE="$DEFAULT_MODE" ;;
+esac
+
+if [ "$MODE" = "block" ]; then
+  echo "trackfw-credential-guard: blocked - possible $MATCH detected in tool payload." >&2
+  exit 2
+fi
 
 echo "trackfw-credential-guard: warning - possible $MATCH detected in tool payload." >&2
 
@@ -459,14 +552,21 @@ function injectClaudeHooks(cwd) {
 
   if (!data.hooks) data.hooks = {}
   data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'AskUserQuestion', SIGNAL_CMD)
-  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A): skip project-scope
-  // credential-guard when the global one is already installed.
+  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A, extended ADR-2026-08-06 emenda 7/ROADMAP-2026-08-08
+  // Wave 2 to Read/Write|Edit): skip project-scope credential-guard when the global one is
+  // already installed for this CLI.
   if (!globalCredentialGuardInstalledClaude()) {
     data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Bash', GUARD_CMD)
+    // ADR-2026-08-06 emenda 7 (2026-08-08): Read/Write/Edit coverage — extraction via direct
+    // file read, or materialization via write/edit, never went through the hook before.
+    data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Read', GUARD_CMD)
+    data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Write|Edit', GUARD_CMD)
   }
   data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'AskUserQuestion', CLEANUP_CMD)
   if (!globalCredentialGuardInstalledClaude()) {
     data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'Bash', GUARD_CMD)
+    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'Read', GUARD_CMD)
+    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'Write|Edit', GUARD_CMD)
   }
 
   writeJSON(filePath, data)
@@ -483,6 +583,12 @@ function injectClaudeHooks(cwd) {
 // are enabled by default (no `[features] hooks = true`/`codex_hooks` opt-in
 // needed -- that flag exists only to turn hooks OFF), and PreToolUse blocking
 // uses exit code 2 + stderr (matching trackfw-credential-guard.sh's "block" mode).
+//
+// Read/Write/Edit coverage (ADR-2026-08-06 emenda 7, ROADMAP-2026-08-08 Wave 2, 2026-08-08):
+// Codex has NO dedicated, interceptable read-tool matcher -- confirmed against
+// https://learn.chatgpt.com/docs/hooks -- so no read matcher is added here; this is a documented
+// limitation (also called out in docs/cli-parity.md), not a workaround. Write/edit materialization
+// IS covered via the `apply_patch` matcher (documented aliases `Edit`/`Write`).
 // ---------------------------------------------------------------------------
 
 function injectCodexHooks(cwd) {
@@ -491,15 +597,18 @@ function injectCodexHooks(cwd) {
 
   if (!data.hooks) data.hooks = {}
   data.hooks.PermissionRequest = mergeClaudeHookArray(data.hooks.PermissionRequest, '.*', SIGNAL_CMD)
-  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A): skip project-scope
-  // credential-guard when the global one is already installed.
+  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A, extended ADR-2026-08-06 emenda 7/ROADMAP-2026-08-08
+  // Wave 2 to apply_patch): skip project-scope credential-guard when the global one is already
+  // installed for this CLI.
   const skipCodexCG = globalCredentialGuardInstalledCodex()
   if (!skipCodexCG) {
     data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Bash', GUARD_CMD)
+    data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'apply_patch', GUARD_CMD)
   }
   data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, '.*', CLEANUP_CMD)
   if (!skipCodexCG) {
     data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'Bash', GUARD_CMD)
+    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'apply_patch', GUARD_CMD)
   }
 
   writeJSON(filePath, data)
@@ -523,6 +632,12 @@ function injectCodexHooks(cwd) {
 // (matcher "*") is the pre-existing attention-cleanup wiring, unrelated to the new
 // credential-guard entry added as a separate array entry (different matcher) in the
 // same event.
+//
+// Read/Write/Edit coverage (ADR-2026-08-06 emenda 7, ROADMAP-2026-08-08 Wave 2, 2026-08-08): the
+// Gemini CLI tools table (https://geminicli.com/docs/reference/tools) documents `read_file`/
+// `read_many_files` as the file-read tools and `write_file`/`replace` as the file-write/edit
+// tools -- matcher below follows the same regex-over-tool_name convention already used for
+// `run_shell_command`.
 // ---------------------------------------------------------------------------
 
 function injectGeminiHooks(cwd) {
@@ -531,15 +646,20 @@ function injectGeminiHooks(cwd) {
 
   if (!data.hooks) data.hooks = {}
   data.hooks.Notification = mergeClaudeHookArray(data.hooks.Notification, 'ToolPermission', SIGNAL_CMD)
-  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A): skip project-scope
+  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A, extended ADR-2026-08-06 emenda 7/ROADMAP-2026-08-08
+  // Wave 2 to read_file|read_many_files / write_file|replace): skip project-scope
   // credential-guard when the global one is already installed.
   const skipGeminiCG = globalCredentialGuardInstalledGemini()
   if (!skipGeminiCG) {
     data.hooks.BeforeTool = mergeClaudeHookArray(data.hooks.BeforeTool, 'run_shell_command', GUARD_CMD)
+    data.hooks.BeforeTool = mergeClaudeHookArray(data.hooks.BeforeTool, 'read_file|read_many_files', GUARD_CMD)
+    data.hooks.BeforeTool = mergeClaudeHookArray(data.hooks.BeforeTool, 'write_file|replace', GUARD_CMD)
   }
   data.hooks.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, '*', CLEANUP_CMD)
   if (!skipGeminiCG) {
     data.hooks.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, 'run_shell_command', GUARD_CMD)
+    data.hooks.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, 'read_file|read_many_files', GUARD_CMD)
+    data.hooks.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, 'write_file|replace', GUARD_CMD)
   }
 
   writeJSON(filePath, data)
@@ -586,8 +706,9 @@ function injectKiroHooks(cwd) {
     },
   ]
 
-  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A): skip project-scope
-  // credential-guard entries when the global one is already installed.
+  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A, extended ADR-2026-08-06 emenda 7/ROADMAP-2026-08-08
+  // Wave 2 to read/write): skip project-scope credential-guard entries when the global one is
+  // already installed.
   if (!globalCredentialGuardInstalledKiro()) {
     hooks.push(
       {
@@ -604,6 +725,36 @@ function injectKiroHooks(cwd) {
         matcher: 'shell',
         action: { type: 'command', command: GUARD_CMD },
       },
+      // Read/Write coverage (ADR-2026-08-06 emenda 7, 2026-08-08): "read" and "write" are the
+      // documented Kiro tool-category aliases (fs_read/fs_write), same pattern as "shell" above.
+      {
+        name: 'trackfw-credential-guard-read-pre',
+        description: 'Blocks/warns on possible plaintext credential materialization before a file read',
+        trigger: 'PreToolUse',
+        matcher: 'read',
+        action: { type: 'command', command: GUARD_CMD },
+      },
+      {
+        name: 'trackfw-credential-guard-read-post',
+        description: 'Warns on possible plaintext credential materialization after a file read',
+        trigger: 'PostToolUse',
+        matcher: 'read',
+        action: { type: 'command', command: GUARD_CMD },
+      },
+      {
+        name: 'trackfw-credential-guard-write-pre',
+        description: 'Blocks/warns on possible plaintext credential materialization before a file write',
+        trigger: 'PreToolUse',
+        matcher: 'write',
+        action: { type: 'command', command: GUARD_CMD },
+      },
+      {
+        name: 'trackfw-credential-guard-write-post',
+        description: 'Warns on possible plaintext credential materialization after a file write',
+        trigger: 'PostToolUse',
+        matcher: 'write',
+        action: { type: 'command', command: GUARD_CMD },
+      },
     )
   }
 
@@ -638,17 +789,27 @@ function injectKiroHooks(cwd) {
 // regardless.
 // ---------------------------------------------------------------------------
 
+// Read/Write coverage (ADR-2026-08-06 emenda 7, ROADMAP-2026-08-08 Wave 2, 2026-08-08):
+// https://docs.github.com/en/copilot/reference/hooks-reference confirms the camelCase
+// preToolUse/postToolUse toolName mapping `view -> Read`, `create -> Write`, `edit -> Edit` --
+// "view" is the read matcher, "create|edit" the write/edit matcher, same lowercase-runtime-name
+// convention already used for "bash" above.
 function injectCopilotHooks(cwd) {
   const filePath = path.join(cwd, '.github', 'hooks', 'trackfw-attention.json')
 
   const preToolUse = [{ type: 'command', bash: SIGNAL_CMD, cwd: '.', timeoutSec: 10 }]
   const postToolUse = [{ type: 'command', bash: CLEANUP_CMD, cwd: '.', timeoutSec: 10 }]
 
-  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A): skip project-scope
-  // credential-guard entries when the global one is already installed.
+  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A, extended ADR-2026-08-06 emenda 7/ROADMAP-2026-08-08
+  // Wave 2 to view / create|edit): skip project-scope credential-guard entries when the global
+  // one is already installed.
   if (!globalCredentialGuardInstalledCopilot()) {
     preToolUse.push({ type: 'command', matcher: 'bash', bash: GUARD_CMD, cwd: '.', timeoutSec: 10 })
+    preToolUse.push({ type: 'command', matcher: 'view', bash: GUARD_CMD, cwd: '.', timeoutSec: 10 })
+    preToolUse.push({ type: 'command', matcher: 'create|edit', bash: GUARD_CMD, cwd: '.', timeoutSec: 10 })
     postToolUse.push({ type: 'command', matcher: 'bash', bash: GUARD_CMD, cwd: '.', timeoutSec: 10 })
+    postToolUse.push({ type: 'command', matcher: 'view', bash: GUARD_CMD, cwd: '.', timeoutSec: 10 })
+    postToolUse.push({ type: 'command', matcher: 'create|edit', bash: GUARD_CMD, cwd: '.', timeoutSec: 10 })
   }
 
   const data = {
@@ -745,7 +906,8 @@ function injectCursorHooks(cwd) {
   }
   removeKnownCommandFromLegacyTopLevelArray(data, 'postToolUse', CLEANUP_CMD)
 
-  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A): skip project-scope
+  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A, extended ADR-2026-08-06 emenda 7/ROADMAP-2026-08-08
+  // Wave 2 to Read/Write via the generic preToolUse/postToolUse events): skip project-scope
   // credential-guard entries when the global one is already installed.
   if (!globalCredentialGuardInstalledCursor()) {
     if (!Array.isArray(data.hooks.beforeShellExecution)) data.hooks.beforeShellExecution = []
@@ -757,6 +919,29 @@ function injectCursorHooks(cwd) {
     if (!hasEntry(data.hooks.afterShellExecution, 'command', GUARD_CMD)) {
       data.hooks.afterShellExecution.push({ command: GUARD_CMD })
     }
+
+    // Read/Write coverage (ADR-2026-08-06 emenda 7, 2026-08-08): wired via the generic
+    // preToolUse/postToolUse events (distinct from beforeShellExecution/afterShellExecution,
+    // which only ever fire for Shell) with an explicit `matcher`, so these entries never fire
+    // for the same tool call the unfiltered attention-signal/cleanup entries already handle
+    // above in this same array. hasEntry (command-only) is not enough here -- both the
+    // unfiltered signal entry and these matcher-scoped guard entries share the same array, so
+    // dedup must also check `matcher`.
+    const hasGuardMatcherEntry = (arr, matcher) =>
+      Array.isArray(arr) && arr.some(e => e && e.command === GUARD_CMD && e.matcher === matcher)
+
+    if (!hasGuardMatcherEntry(data.hooks.preToolUse, 'Read')) {
+      data.hooks.preToolUse.push({ command: GUARD_CMD, matcher: 'Read' })
+    }
+    if (!hasGuardMatcherEntry(data.hooks.preToolUse, 'Write')) {
+      data.hooks.preToolUse.push({ command: GUARD_CMD, matcher: 'Write' })
+    }
+    if (!hasGuardMatcherEntry(data.hooks.postToolUse, 'Read')) {
+      data.hooks.postToolUse.push({ command: GUARD_CMD, matcher: 'Read' })
+    }
+    if (!hasGuardMatcherEntry(data.hooks.postToolUse, 'Write')) {
+      data.hooks.postToolUse.push({ command: GUARD_CMD, matcher: 'Write' })
+    }
   }
 
   writeJSON(filePath, data)

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

@@ -63,7 +63,10 @@
         "domainQuestion_persistence": "Which database engine will be used?",
         "domainQuestion_api": "Which API protocol will be used?",
         "domainQuestion_deploy": "What is the deployment target?",
-        "domainQuestion_events": "Which event broker will be used?"
+        "domainQuestion_events": "Which event broker will be used?",
+        "adrScope": "Scope of ADRs for this REQ",
+        "adrScopeLocal": "Local (default)",
+        "adrScopeGlobal": "Global (~/.trackfw/adr, cross-project)"
       },
       "detectedDomains": "Detected domains: {{domains}}",
       "created": "✓ REQ created: {{path}}",

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

@@ -63,7 +63,10 @@
         "domainQuestion_persistence": "¿Qué motor de base de datos se usará?",
         "domainQuestion_api": "¿Qué protocolo de API se usará?",
         "domainQuestion_deploy": "¿Cuál es el destino de despliegue?",
-        "domainQuestion_events": "¿Qué message broker se usará?"
+        "domainQuestion_events": "¿Qué message broker se usará?",
+        "adrScope": "Alcance de los ADRs de este REQ",
+        "adrScopeLocal": "Local (predeterminado)",
+        "adrScopeGlobal": "Global (~/.trackfw/adr, entre proyectos)"
       },
       "detectedDomains": "Dominios detectados: {{domains}}",
       "created": "✓ REQ creado: {{path}}",

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

@@ -63,7 +63,10 @@
         "domainQuestion_persistence": "Qual engine de banco de dados será usada?",
         "domainQuestion_api": "Qual protocolo de API será usado?",
         "domainQuestion_deploy": "Qual é o destino de deploy?",
-        "domainQuestion_events": "Qual message broker será usado?"
+        "domainQuestion_events": "Qual message broker será usado?",
+        "adrScope": "Escopo dos ADRs desta REQ",
+        "adrScopeLocal": "Local (padrão)",
+        "adrScopeGlobal": "Global (~/.trackfw/adr, entre projetos)"
       },
       "detectedDomains": "Domínios detectados: {{domains}}",
       "created": "✓ REQ criado: {{path}}",