trackfw 6.4.1 → 6.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "6.4.1",
+  "version": "6.5.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/discover.js

@@ -441,6 +441,12 @@ cmd.action((opts) => {
       } catch (e) {
         console.warn(`⚠ attention scripts: ${e.message}`);
       }
+      try {
+        const { generateCredentialGuardScript } = require('../generators/hooks');
+        generateCredentialGuardScript(cwd);
+      } catch (e) {
+        console.warn(`⚠ credential guard script: ${e.message}`);
+      }
       try {
         const { injectHooksDetected } = require('../generators/hooks');
         injectHooksDetected(cwd);

package/src/commands/update-harness.js

@@ -6,6 +6,7 @@ const path = require('path')
 const identityStore = require('../identity')
 const { catalog, buildPlans, IntegrationManager, globalGroupPath } = require('../integrations')
 const { tildeify, validateTargets, buildDocument, humanReport, silenceConsole } = require('../lib/update-engine')
+const { mergeClaudeHookArray, mergeSimpleCommandArray, mergeCopilotHookArray } = require('../generators/hooks')
 
 // `trackfw update harness` is the global counterpart to `trackfw update` —
 // see docs/cli-parity.md, "`trackfw update` vs `trackfw update harness`".
@@ -93,6 +94,374 @@ function claudeSkillTarget(homeRoot, { dryRun, installMissing }) {
   }
 }
 
+// credentialGuardTargetClaude — evaluates (and, unless --dry-run, applies) the
+// global-scope credential-guard hook wiring for Claude Code:
+// PreToolUse[matcher:"Bash"]/PostToolUse[matcher:"Bash"] entries in
+// ~/.claude/settings.json pointing at the ABSOLUTE path of
+// ~/.trackfw/scripts/trackfw-credential-guard.sh (a global hook can fire from
+// any project's cwd, unlike the project-scope wiring's relative
+// "scripts/trackfw-credential-guard.sh"). Mirrors
+// internal/generators/update.go:harnessCredentialGuardTargetClaude —
+// including deliberately NOT calling generateGlobalCredentialGuardScript here
+// (writing the referenced script file itself is out of this target's scope,
+// same as the Go implementation). Reuses mergeClaudeHookArray (generators/
+// hooks.js) so any pre-existing content in ~/.claude/settings.json (other
+// hooks, user config) is preserved — only the credential-guard entry is
+// added/merged.
+function credentialGuardTargetClaude(homeRoot, { dryRun, installMissing }) {
+  const id = 'claude-credential-guard'
+  const filePath = path.join(homeRoot, '.claude', 'settings.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-credential-guard.sh')
+
+  let root
+  let raw = null
+  try {
+    if (fs.existsSync(filePath)) {
+      raw = fs.readFileSync(filePath, 'utf8')
+      root = raw.length ? JSON.parse(raw) : {}
+    } else {
+      if (!installMissing) return { id, state: 'missing', path: displayPath }
+      if (dryRun) return { id, state: 'updated', path: displayPath }
+      root = {}
+      if (!root.hooks) root.hooks = {}
+      root.hooks.PreToolUse = mergeClaudeHookArray(root.hooks.PreToolUse, 'Bash', scriptPath)
+      root.hooks.PostToolUse = mergeClaudeHookArray(root.hooks.PostToolUse, 'Bash', scriptPath)
+      const desired = JSON.stringify(root, null, 2) + '\n'
+      fs.mkdirSync(path.dirname(filePath), { recursive: true })
+      fs.writeFileSync(filePath, desired, 'utf8')
+      return { id, state: 'updated', path: displayPath }
+    }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+
+  try {
+    if (!root.hooks) root.hooks = {}
+    root.hooks.PreToolUse = mergeClaudeHookArray(root.hooks.PreToolUse, 'Bash', scriptPath)
+    root.hooks.PostToolUse = mergeClaudeHookArray(root.hooks.PostToolUse, 'Bash', scriptPath)
+    const desired = JSON.stringify(root, null, 2) + '\n'
+    if (desired === raw) return { id, state: 'skipped', path: displayPath }
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+// credentialGuardTargetCodex — evaluates (and, unless --dry-run, applies) the
+// global-scope credential-guard hook wiring for Codex CLI:
+// PreToolUse[matcher:"Bash"]/PostToolUse[matcher:"Bash"] entries in
+// ~/.codex/hooks.json pointing at the ABSOLUTE path of
+// ~/.trackfw/scripts/trackfw-credential-guard.sh — mirrors
+// credentialGuardTargetClaude exactly (same 4-state contract, same idempotent
+// merge via mergeClaudeHookArray, same reason for an absolute path). Mirrors
+// internal/generators/update.go:harnessCredentialGuardTargetCodex.
+//
+// Investigation (ROADMAP-2026-08-06 Wave 2/ML-2B, confirmed 2026-08-06
+// against https://developers.openai.com/codex/hooks): "Hooks are enabled by
+// default. To turn them off in config.toml, set: [features] hooks = false.
+// Use hooks as the canonical feature key. codex_hooks still works as a
+// deprecated alias." No `[features] codex_hooks = true` opt-in is required
+// — the flag exists only to turn hooks OFF and is a deprecated alias for the
+// canonical `hooks` key. https://developers.openai.com/codex/config-advanced
+// (also fetched 2026-08-06) has no conflicting requirement.
+function credentialGuardTargetCodex(homeRoot, { dryRun, installMissing }) {
+  const id = 'codex-credential-guard'
+  const filePath = path.join(homeRoot, '.codex', 'hooks.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-credential-guard.sh')
+
+  let root
+  let raw = null
+  try {
+    if (fs.existsSync(filePath)) {
+      raw = fs.readFileSync(filePath, 'utf8')
+      root = raw.length ? JSON.parse(raw) : {}
+    } else {
+      if (!installMissing) return { id, state: 'missing', path: displayPath }
+      if (dryRun) return { id, state: 'updated', path: displayPath }
+      root = {}
+      if (!root.hooks) root.hooks = {}
+      root.hooks.PreToolUse = mergeClaudeHookArray(root.hooks.PreToolUse, 'Bash', scriptPath)
+      root.hooks.PostToolUse = mergeClaudeHookArray(root.hooks.PostToolUse, 'Bash', scriptPath)
+      const desired = JSON.stringify(root, null, 2) + '\n'
+      fs.mkdirSync(path.dirname(filePath), { recursive: true })
+      fs.writeFileSync(filePath, desired, 'utf8')
+      return { id, state: 'updated', path: displayPath }
+    }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+
+  try {
+    if (!root.hooks) root.hooks = {}
+    root.hooks.PreToolUse = mergeClaudeHookArray(root.hooks.PreToolUse, 'Bash', scriptPath)
+    root.hooks.PostToolUse = mergeClaudeHookArray(root.hooks.PostToolUse, 'Bash', scriptPath)
+    const desired = JSON.stringify(root, null, 2) + '\n'
+    if (desired === raw) return { id, state: 'skipped', path: displayPath }
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+// credentialGuardTargetGemini — evaluates (and, unless --dry-run, applies)
+// the global-scope credential-guard hook wiring for Gemini CLI:
+// BeforeTool[matcher:"run_shell_command"]/AfterTool[matcher:"run_shell_command"]
+// entries in ~/.gemini/settings.json pointing at the ABSOLUTE path of
+// ~/.trackfw/scripts/trackfw-credential-guard.sh — mirrors
+// credentialGuardTargetClaude/credentialGuardTargetCodex exactly (same
+// 4-state contract, same idempotent merge via mergeClaudeHookArray), only the
+// top-level event key names differ (BeforeTool/AfterTool instead of
+// PreToolUse/PostToolUse, and matcher "run_shell_command" instead of "Bash")
+// since Gemini CLI uses a different hook vocabulary than Claude/Codex (see
+// generators/hooks.js:injectGeminiHooks, confirmed against
+// https://geminicli.com/docs/hooks/reference). Mirrors
+// internal/generators/update.go:harnessCredentialGuardTargetGemini.
+function credentialGuardTargetGemini(homeRoot, { dryRun, installMissing }) {
+  const id = 'gemini-credential-guard'
+  const filePath = path.join(homeRoot, '.gemini', 'settings.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-credential-guard.sh')
+
+  let root
+  let raw = null
+  try {
+    if (fs.existsSync(filePath)) {
+      raw = fs.readFileSync(filePath, 'utf8')
+      root = raw.length ? JSON.parse(raw) : {}
+    } else {
+      if (!installMissing) return { id, state: 'missing', path: displayPath }
+      if (dryRun) return { id, state: 'updated', path: displayPath }
+      root = {}
+      if (!root.hooks) root.hooks = {}
+      root.hooks.BeforeTool = mergeClaudeHookArray(root.hooks.BeforeTool, 'run_shell_command', scriptPath)
+      root.hooks.AfterTool = mergeClaudeHookArray(root.hooks.AfterTool, 'run_shell_command', scriptPath)
+      const desired = JSON.stringify(root, null, 2) + '\n'
+      fs.mkdirSync(path.dirname(filePath), { recursive: true })
+      fs.writeFileSync(filePath, desired, 'utf8')
+      return { id, state: 'updated', path: displayPath }
+    }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+
+  try {
+    if (!root.hooks) root.hooks = {}
+    root.hooks.BeforeTool = mergeClaudeHookArray(root.hooks.BeforeTool, 'run_shell_command', scriptPath)
+    root.hooks.AfterTool = mergeClaudeHookArray(root.hooks.AfterTool, 'run_shell_command', scriptPath)
+    const desired = JSON.stringify(root, null, 2) + '\n'
+    if (desired === raw) return { id, state: 'skipped', path: displayPath }
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+// credentialGuardTargetCursor — evaluates (and, unless --dry-run, applies)
+// the global-scope credential-guard hook wiring for Cursor:
+// hooks.beforeShellExecution/hooks.afterShellExecution entries in
+// ~/.cursor/hooks.json pointing at the ABSOLUTE path of
+// ~/.trackfw/scripts/trackfw-credential-guard.sh — same 4-state contract and
+// same reason for an absolute path as credentialGuardTargetClaude/Codex/
+// Gemini (a global hook can fire from any project's cwd), but via
+// mergeSimpleCommandArray (generators/hooks.js) instead of
+// mergeClaudeHookArray: Cursor's hooks.json schema
+// (`{"version":1,"hooks":{"<event>":[{"command":"..."}]}}`, confirmed by
+// generators/hooks.js:injectCursorHooks) is structurally different from
+// Claude/Codex/Gemini's — each event array holds flat {"command":"..."}
+// entries, no per-entry "matcher", no nested {"type","hooks":[...]}. Mirrors
+// internal/generators/update.go:harnessCredentialGuardTargetCursor.
+function credentialGuardTargetCursor(homeRoot, { dryRun, installMissing }) {
+  const id = 'cursor-credential-guard'
+  const filePath = path.join(homeRoot, '.cursor', 'hooks.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-credential-guard.sh')
+
+  let root
+  let raw = null
+  try {
+    if (fs.existsSync(filePath)) {
+      raw = fs.readFileSync(filePath, 'utf8')
+      root = raw.length ? JSON.parse(raw) : {}
+    } else {
+      if (!installMissing) return { id, state: 'missing', path: displayPath }
+      if (dryRun) return { id, state: 'updated', path: displayPath }
+      root = {}
+      if (typeof root.version === 'undefined') root.version = 1
+      if (!root.hooks) root.hooks = {}
+      root.hooks.beforeShellExecution = mergeSimpleCommandArray(root.hooks.beforeShellExecution, scriptPath)
+      root.hooks.afterShellExecution = mergeSimpleCommandArray(root.hooks.afterShellExecution, scriptPath)
+      const desired = JSON.stringify(root, null, 2) + '\n'
+      fs.mkdirSync(path.dirname(filePath), { recursive: true })
+      fs.writeFileSync(filePath, desired, 'utf8')
+      return { id, state: 'updated', path: displayPath }
+    }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+
+  try {
+    if (typeof root.version === 'undefined') root.version = 1
+    if (!root.hooks) root.hooks = {}
+    root.hooks.beforeShellExecution = mergeSimpleCommandArray(root.hooks.beforeShellExecution, scriptPath)
+    root.hooks.afterShellExecution = mergeSimpleCommandArray(root.hooks.afterShellExecution, scriptPath)
+    const desired = JSON.stringify(root, null, 2) + '\n'
+    if (desired === raw) return { id, state: 'skipped', path: displayPath }
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+// credentialGuardTargetCopilot — evaluates (and, unless --dry-run, applies)
+// the global-scope credential-guard hook wiring for GitHub Copilot:
+// hooks.preToolUse/hooks.postToolUse[matcher:"bash"] entries in
+// ~/.copilot/settings.json pointing at the ABSOLUTE path of
+// ~/.trackfw/scripts/trackfw-credential-guard.sh — same 4-state contract and
+// same reason for an absolute path as credentialGuardTargetClaude/Codex/
+// Gemini/Cursor (a global hook can fire from any project's cwd), but via
+// mergeCopilotHookArray (generators/hooks.js) since Copilot's command-hook
+// entry shape differs from every other tool's (ROADMAP-2026-08-06 ML-2E —
+// see that helper's doc comment and
+// internal/generators/update.go:mergeCredentialGuardCopilotHooks for the
+// full ~/.copilot/settings.json format investigation, including why no
+// top-level "version" key is added: settings.json is Copilot CLI's general
+// user config file, not a dedicated hooks file). Mirrors
+// internal/generators/update.go:harnessCredentialGuardTargetCopilot.
+function credentialGuardTargetCopilot(homeRoot, { dryRun, installMissing }) {
+  const id = 'copilot-credential-guard'
+  const filePath = path.join(homeRoot, '.copilot', 'settings.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-credential-guard.sh')
+
+  let root
+  let raw = null
+  try {
+    if (fs.existsSync(filePath)) {
+      raw = fs.readFileSync(filePath, 'utf8')
+      root = raw.length ? JSON.parse(raw) : {}
+    } else {
+      if (!installMissing) return { id, state: 'missing', path: displayPath }
+      if (dryRun) return { id, state: 'updated', path: displayPath }
+      root = {}
+      if (!root.hooks) root.hooks = {}
+      root.hooks.preToolUse = mergeCopilotHookArray(root.hooks.preToolUse, scriptPath)
+      root.hooks.postToolUse = mergeCopilotHookArray(root.hooks.postToolUse, scriptPath)
+      const desired = JSON.stringify(root, null, 2) + '\n'
+      fs.mkdirSync(path.dirname(filePath), { recursive: true })
+      fs.writeFileSync(filePath, desired, 'utf8')
+      return { id, state: 'updated', path: displayPath }
+    }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+
+  try {
+    if (!root.hooks) root.hooks = {}
+    root.hooks.preToolUse = mergeCopilotHookArray(root.hooks.preToolUse, scriptPath)
+    root.hooks.postToolUse = mergeCopilotHookArray(root.hooks.postToolUse, scriptPath)
+    const desired = JSON.stringify(root, null, 2) + '\n'
+    if (desired === raw) return { id, state: 'skipped', path: displayPath }
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+// credentialGuardTargetKiro — evaluates (and, unless --dry-run, applies) the
+// global-scope credential-guard hook wiring for Kiro: a DEDICATED file at
+// ~/.kiro/hooks/trackfw-credential-guard.json (unlike claude/codex/gemini/
+// cursor/copilot-credential-guard, which merge into a shared, general
+// settings file — ~/.kiro/hooks/ is a directory of one-file-per-hook,
+// confirmed by generators/hooks.js:injectKiroHooks's own investigation and
+// by kiro.dev/changelog/cli/2-13/: "Hooks placed in ~/.kiro/hooks/ now fire
+// in every workspace automatically ... Workspace-level hooks continue to
+// work alongside global ones"). Same schema as injectKiroHooks (project
+// scope): top-level {"version":"v1","hooks":[...]}, each entry
+// {"name","description","trigger","matcher","action":{"type":"command",
+// "command":<absolute path>}} — but the command here is the ABSOLUTE path
+// of ~/.trackfw/scripts/trackfw-credential-guard.sh (a global hook can fire
+// from any project's cwd), and the two hook names are
+// "trackfw-credential-guard-global-pre"/"-global-post" — deliberately
+// DISTINCT from the project-scope names ("trackfw-credential-guard-pre"/
+// "-post") since this writes an entirely different file and nothing
+// documents whether Kiro deduplicates same-named hooks across scopes/files;
+// ML-3A's future project-scope dedup will match on the script path, not the
+// hook name.
+//
+// Kiro v3 caveat (ROADMAP-2026-08-06 Wave 2/ML-2F, confirmed 2026-08-06
+// against kiro.dev/changelog/cli/2-13/): global hooks are "Available in V3
+// (`kiro-cli --v3`)". `--v3` is a LAUNCH-MODE flag on the same installed
+// binary, not a value any `--version`-style command reports — there is no
+// documented `kiro`/`kiro-cli --version` output format anywhere in the
+// fetched sources, and no persistent installed-version fact to probe from a
+// separate process (trackfw never invokes Kiro itself). This target does
+// NOT attempt a subprocess version probe, and does NOT put the caveat in
+// the JSON `message` field either (pinned contract: `message` is
+// failure-only — see docs/cli-parity.md and
+// internal/commands/update_harness_test.go's
+// TestUpdateHarnessCmd_JSONKeyOrderMatchesCliParityContract). The v3
+// prerequisite is documented here and in docs/cli-parity.md's own "Kiro
+// global-scope wiring (ML-2F)" section instead. Mirrors
+// internal/generators/update.go:harnessCredentialGuardTargetKiro.
+function credentialGuardTargetKiro(homeRoot, { dryRun, installMissing }) {
+  const id = 'kiro-credential-guard'
+  const filePath = path.join(homeRoot, '.kiro', 'hooks', 'trackfw-credential-guard.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-credential-guard.sh')
+
+  const desired = JSON.stringify(
+    {
+      version: 'v1',
+      hooks: [
+        {
+          name: 'trackfw-credential-guard-global-pre',
+          description: 'Blocks/warns on possible plaintext credential materialization before a shell command executes (global, all projects)',
+          trigger: 'PreToolUse',
+          matcher: 'shell',
+          action: { type: 'command', command: scriptPath },
+        },
+        {
+          name: 'trackfw-credential-guard-global-post',
+          description: 'Warns on possible plaintext credential materialization after a shell command executes (global, all projects)',
+          trigger: 'PostToolUse',
+          matcher: 'shell',
+          action: { type: 'command', command: scriptPath },
+        },
+      ],
+    },
+    null,
+    2
+  ) + '\n'
+
+  try {
+    const exists = fs.existsSync(filePath)
+    const actual = exists ? fs.readFileSync(filePath, 'utf8') : null
+
+    if (!exists && !installMissing) return { id, state: 'missing', path: displayPath }
+    if (exists && actual === desired) return { id, state: 'skipped', path: displayPath }
+
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
 // catalogBundleTarget — one target per (tool, kind) pair at global scope.
 // Uses IntegrationManager.inspect (read-only) to classify every catalog
 // item under that pair, then only calls manager.update() for the subset
@@ -136,8 +505,19 @@ function catalogBundleTarget(toolId, kind, homeRoot, identityConfig, { dryRun, i
   }
 }
 
-const HARNESS_TARGET_IDS = ['claude-skill']
+// HARNESS_TARGET_IDS — mirrors internal/generators/update.go:HarnessTargetIDs.
+// "codex-credential-guard"/"gemini-credential-guard" are each inserted
+// immediately BEFORE their tool's "-agents"/"-skills" pair (same relative
+// position as claude-credential-guard, which precedes claude-agents/
+// claude-skills) — see buildHarnessTargetIDs's comment in update.go for the
+// full rationale.
+const HARNESS_TARGET_IDS = ['claude-skill', 'claude-credential-guard']
 for (const target of catalog.targets) {
+  if (target.id === 'codex') HARNESS_TARGET_IDS.push('codex-credential-guard')
+  if (target.id === 'gemini') HARNESS_TARGET_IDS.push('gemini-credential-guard')
+  if (target.id === 'cursor') HARNESS_TARGET_IDS.push('cursor-credential-guard')
+  if (target.id === 'copilot') HARNESS_TARGET_IDS.push('copilot-credential-guard')
+  if (target.id === 'kiro') HARNESS_TARGET_IDS.push('kiro-credential-guard')
   HARNESS_TARGET_IDS.push(`${target.id}-agents`, `${target.id}-skills`)
 }
 
@@ -150,7 +530,23 @@ function buildHarnessTargets(homeRoot, identityConfig, { dryRun, installMissing
   const include = (id) => !wanted || wanted.includes(id)
   const targets = []
   if (include('claude-skill')) targets.push(claudeSkillTarget(homeRoot, { dryRun, installMissing }))
+  if (include('claude-credential-guard')) targets.push(credentialGuardTargetClaude(homeRoot, { dryRun, installMissing }))
   for (const target of catalog.targets) {
+    if (target.id === 'codex' && include('codex-credential-guard')) {
+      targets.push(credentialGuardTargetCodex(homeRoot, { dryRun, installMissing }))
+    }
+    if (target.id === 'gemini' && include('gemini-credential-guard')) {
+      targets.push(credentialGuardTargetGemini(homeRoot, { dryRun, installMissing }))
+    }
+    if (target.id === 'cursor' && include('cursor-credential-guard')) {
+      targets.push(credentialGuardTargetCursor(homeRoot, { dryRun, installMissing }))
+    }
+    if (target.id === 'copilot' && include('copilot-credential-guard')) {
+      targets.push(credentialGuardTargetCopilot(homeRoot, { dryRun, installMissing }))
+    }
+    if (target.id === 'kiro' && include('kiro-credential-guard')) {
+      targets.push(credentialGuardTargetKiro(homeRoot, { dryRun, installMissing }))
+    }
     const agentsId = `${target.id}-agents`
     const skillsId = `${target.id}-skills`
     if (include(agentsId)) targets.push(catalogBundleTarget(target.id, 'agents', homeRoot, identityConfig, { dryRun, installMissing }))
@@ -205,4 +601,15 @@ function run(options) {
   if (doc.summary.failed > 0) process.exitCode = 1
 }
 
-module.exports = { run, HARNESS_TARGET_IDS, buildHarnessTargets, claudeSkillContent }
+module.exports = {
+  run,
+  HARNESS_TARGET_IDS,
+  buildHarnessTargets,
+  claudeSkillContent,
+  credentialGuardTargetClaude,
+  credentialGuardTargetCodex,
+  credentialGuardTargetGemini,
+  credentialGuardTargetCursor,
+  credentialGuardTargetCopilot,
+  credentialGuardTargetKiro,
+}

package/src/commands/update.js

@@ -130,7 +130,7 @@ function buildProjectTargets(cwd, cfg, identityConfig, { dryRun, installMissing
 
   if (include('agent-hooks')) targets.push(runFileTarget({
     id: 'agent-hooks',
-    path: '.claude/settings.json, .codex/hooks.json, .gemini/settings.json, .kiro/hooks/trackfw-attention.json, .github/hooks/trackfw-attention.json, .cursor/hooks.json, scripts/trackfw-attention-*.sh',
+    path: '.claude/settings.json, .codex/hooks.json, .gemini/settings.json, .kiro/hooks/trackfw-attention.json, .github/hooks/trackfw-attention.json, .cursor/hooks.json, scripts/trackfw-attention-*.sh, scripts/trackfw-credential-guard.sh',
     root: cwd,
     relPaths: [
       '.claude/settings.json',
@@ -141,10 +141,12 @@ function buildProjectTargets(cwd, cfg, identityConfig, { dryRun, installMissing
       '.cursor/hooks.json',
       'scripts/trackfw-attention-signal.sh',
       'scripts/trackfw-attention-cleanup.sh',
+      'scripts/trackfw-credential-guard.sh',
     ],
     apply: (root) => {
       hooksGen.injectHooksDetected(root);
       hooksGen.generateAttentionScripts(cfg, root);
+      hooksGen.generateCredentialGuardScript(root);
     },
     dryRun,
     installMissing,

package/src/config/index.js

@@ -57,6 +57,11 @@ function defaults() {
       jiraToken: '',
       jiraProject: '',
     },
+    // credential_guard field — see ADR-2026-08-05-hook-de-guarda-contra-materializacao-de-
+    // credenciais-reais-por-subagentes.md.
+    credentialGuard: {
+      mode: 'warn',
+    },
     rules: {
       wip_has_req:          'error',
       wip_acceptance:       'error',
@@ -260,6 +265,15 @@ function parse(content, cfg) {
   if (stringVal(m, 'jira_token') !== undefined) cfg.sync.jiraToken = m.jira_token;
   if (stringVal(m, 'jira_project') !== undefined) cfg.sync.jiraProject = m.jira_project;
 
+  // credential_guard field — nested mapping, same shape as link_fields above. An unrecognized
+  // mode value (or an absent/malformed credential_guard block) falls back to the safe default
+  // ("warn") silently, matching how every other unrecognized-shape field in this parser behaves
+  // (e.g. roadmap_namespacing, forge) — no fatal path, no stderr message, for one enum key.
+  if (m.credential_guard !== undefined && typeof m.credential_guard === 'object' && !Array.isArray(m.credential_guard)) {
+    const mode = stringVal(m.credential_guard, 'mode');
+    if (mode === 'warn' || mode === 'block') cfg.credentialGuard.mode = mode;
+  }
+
   return false;
 }
 

package/src/generators/hooks.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs')
 const path = require('path')
+const os = require('os')
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -28,6 +29,37 @@ function hasEntry(arr, field, value) {
   return Array.isArray(arr) && arr.some(e => e && e[field] === value)
 }
 
+/**
+ * Merge helper para arrays de hooks "simples" tipo Cursor
+ * (hooks.beforeShellExecution/afterShellExecution): cada entry é um objeto
+ * plano {"command": "..."} — sem matcher, sem {type, hooks:[...]} aninhado
+ * como Claude/Codex/Gemini. Mirrors internal/generators/agentfiles.go:
+ * mergeSimpleCommandArray.
+ */
+function mergeSimpleCommandArray(existing, command) {
+  const arr = Array.isArray(existing) ? existing.slice() : []
+  if (hasEntry(arr, 'command', command)) return arr
+  arr.push({ command })
+  return arr
+}
+
+/**
+ * Merge helper para arrays de hooks tipo GitHub Copilot
+ * (hooks.preToolUse/postToolUse): cada entry é
+ * {"type":"command","matcher":"bash","bash":"...","cwd":".","timeoutSec":10}
+ * — o campo de match é "bash" (não "command", como no shape "simples" do
+ * Cursor), então mergeSimpleCommandArray não serve aqui.
+ * Mirrors internal/generators/update.go:mergeCredentialGuardCopilotHooks
+ * (ROADMAP-2026-08-06 Wave 2/ML-2E — see that Go function's doc comment for
+ * the full ~/.copilot/settings.json format investigation).
+ */
+function mergeCopilotHookArray(existing, scriptPath) {
+  const arr = Array.isArray(existing) ? existing.slice() : []
+  if (hasEntry(arr, 'bash', scriptPath)) return arr
+  arr.push({ type: 'command', matcher: 'bash', bash: scriptPath, cwd: '.', timeoutSec: 10 })
+  return arr
+}
+
 /** Merge helper para arrays de hooks tipo Claude / Codex / Gemini */
 function mergeClaudeHookArray(existing, matcher, command) {
   const arr = Array.isArray(existing) ? existing : []
@@ -113,8 +145,290 @@ rm -f "$ROADMAP_DIR/.trackfw-attention.json"
 exit 0
 `
 
+// CG_HEADER/CG_PROJECT_GUARD/CG_DETECTION_CORE/CG_PROJECT_TAIL/CG_GLOBAL_TAIL compõem
+// CREDENTIAL_GUARD_SCRIPT (escopo de projeto) e GLOBAL_CREDENTIAL_GUARD_SCRIPT (escopo global,
+// ~/.trackfw/scripts/, instalado via `trackfw update harness`) sem duplicar a lógica de detecção
+// JWT/AWS-key em dois lugares — espelha a mesma decomposição em internal/generators/scaffold.go
+// (credentialGuardHeader/credentialGuardDetectionCore/...).
+
+const CG_HEADER = `#!/usr/bin/env bash
+# trackfw credential guard — PreToolUse/PostToolUse hook
+set -euo pipefail
+
+INPUT=$(cat)
+
+`
+
+const CG_PROJECT_GUARD = `# Script is intentionally a no-op when executed outside the project root
+[ -f "trackfw.yaml" ] || exit 0
+
+`
+
+const CG_DETECTION_CORE = `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
+
+[ -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
+# 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)
+
+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
+
+`
+
+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)
+case "$MODE" in
+  warn|block) ;;
+  *) MODE="warn" ;;
+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
+`
+
+// 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"
+
+echo "trackfw-credential-guard: warning - possible $MATCH detected in tool payload." >&2
+
+ROADMAP_DIR="docs/roadmaps"
+if [ ! -d "$ROADMAP_DIR" ]; then
+  exit 0
+fi
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+MSG="Possible $MATCH detected in tool payload - review before materializing credentials in plain text."
+MSG_ESC=$(echo "$MSG" | tr -d '\\000-\\037' | sed 's/\\\\/\\\\\\\\/g; s/"/\\\\"/g')
+
+mkdir -p "$ROADMAP_DIR"
+printf '{"tool":"credential-guard","message":"%s","level":"action_required","timestamp":"%s"}\\n' \\
+  "$MSG_ESC" \\
+  "$TIMESTAMP" > "$ROADMAP_DIR/.trackfw-credential-guard.json"
+
+exit 0
+`
+
+const CREDENTIAL_GUARD_SCRIPT = CG_HEADER + CG_PROJECT_GUARD + CG_DETECTION_CORE + CG_PROJECT_TAIL
+
+const GLOBAL_CREDENTIAL_GUARD_SCRIPT = CG_HEADER + CG_DETECTION_CORE + CG_GLOBAL_TAIL
+
+// ---------------------------------------------------------------------------
+// generateCredentialGuardScript — writes scripts/trackfw-credential-guard.sh
+// ---------------------------------------------------------------------------
+// ML-1A only: creates the script. It is NOT wired into any hooks.json/settings.json
+// here -- that is Wave 2's scope (see ROADMAP-2026-08-05-hooks-de-guarda-contra-
+// materializacao-de-credenciais-reais-por-subagentes.md).
+function generateCredentialGuardScript(cwd) {
+  const root = cwd || process.cwd()
+  const scriptsDir = path.join(root, 'scripts')
+  fs.mkdirSync(scriptsDir, { recursive: true })
+
+  const scriptPath = path.join(scriptsDir, 'trackfw-credential-guard.sh')
+  fs.writeFileSync(scriptPath, CREDENTIAL_GUARD_SCRIPT, { encoding: 'utf8', mode: 0o755 })
+
+  console.log('  ✓ scripts/trackfw-credential-guard.sh')
+}
+
+// ---------------------------------------------------------------------------
+// generateGlobalCredentialGuardScript — writes <home>/.trackfw/scripts/trackfw-credential-guard.sh
+// ---------------------------------------------------------------------------
+// Destinado a ser referenciado por hooks globais de CLI, instalados via `trackfw update harness`
+// (ver ROADMAP-2026-08-06, Wave 2) -- não é chamado por `trackfw init`/`trackfw update` (escopo de
+// projeto), que continuam usando generateCredentialGuardScript.
+function generateGlobalCredentialGuardScript(home) {
+  if (!home) {
+    throw new Error('home directory vazio')
+  }
+  const scriptsDir = path.join(home, '.trackfw', 'scripts')
+  fs.mkdirSync(scriptsDir, { recursive: true })
+
+  const scriptPath = path.join(scriptsDir, 'trackfw-credential-guard.sh')
+  fs.writeFileSync(scriptPath, GLOBAL_CREDENTIAL_GUARD_SCRIPT, { encoding: 'utf8', mode: 0o755 })
+
+  console.log('  ✓ .trackfw/scripts/trackfw-credential-guard.sh')
+}
+
 const SIGNAL_CMD = 'scripts/trackfw-attention-signal.sh'
 const CLEANUP_CMD = 'scripts/trackfw-attention-cleanup.sh'
+const GUARD_CMD = 'scripts/trackfw-credential-guard.sh'
+
+// ---------------------------------------------------------------------------
+// Global credential-guard dedup (ROADMAP-2026-08-06 Wave 3/ML-3A)
+// ---------------------------------------------------------------------------
+// injectClaudeHooks/injectCodexHooks/injectGeminiHooks/injectCursorHooks/
+// injectCopilotHooks/injectKiroHooks each check, read-only, whether the user
+// already has the global-scope credential-guard wiring installed for that
+// CLI (via `trackfw update harness --targets <tool>-credential-guard`,
+// npm/src/commands/update-harness.js) before adding the project-scope
+// credential-guard entry. If the global entry is already present, the
+// project-scope entry is skipped entirely — attention-signal/cleanup are
+// unaffected (inherently project-scoped, ADR-2026-08-06 Decision #4).
+//
+// Fail-open is mandatory: any failure to resolve $HOME, read the global
+// file, or parse its JSON is treated as "not installed globally" -- this
+// section never writes to the global file (read-only by construction).
+
+/** Mirrors Go's globalCredentialGuardScriptPath. */
+function globalCredentialGuardScriptPath() {
+  const home = os.homedir()
+  if (!home) return null
+  return path.join(home, '.trackfw', 'scripts', 'trackfw-credential-guard.sh')
+}
+
+/** Reads+parses JSON at $HOME/<...relParts>; returns null on any failure (fail-open). */
+function readGlobalHookJSON(...relParts) {
+  const home = os.homedir()
+  if (!home) return null
+  try {
+    const raw = fs.readFileSync(path.join(home, ...relParts), 'utf8')
+    return JSON.parse(raw)
+  } catch (_) {
+    return null
+  }
+}
+
+/** Read-only counterpart of mergeClaudeHookArray. */
+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
+  }
+  return false
+}
+
+function globalCredentialGuardInstalledClaude() {
+  const scriptPath = globalCredentialGuardScriptPath()
+  if (!scriptPath) return false
+  const root = readGlobalHookJSON('.claude', 'settings.json')
+  if (!root || !root.hooks) return false
+  return hookArrayHasCommand(root.hooks.PreToolUse, 'Bash', scriptPath)
+}
+
+function globalCredentialGuardInstalledCodex() {
+  const scriptPath = globalCredentialGuardScriptPath()
+  if (!scriptPath) return false
+  const root = readGlobalHookJSON('.codex', 'hooks.json')
+  if (!root || !root.hooks) return false
+  return hookArrayHasCommand(root.hooks.PreToolUse, 'Bash', scriptPath)
+}
+
+function globalCredentialGuardInstalledGemini() {
+  const scriptPath = globalCredentialGuardScriptPath()
+  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 globalCredentialGuardInstalledCursor() {
+  const scriptPath = globalCredentialGuardScriptPath()
+  if (!scriptPath) return false
+  const root = readGlobalHookJSON('.cursor', 'hooks.json')
+  if (!root || !root.hooks) return false
+  return hasEntry(root.hooks.beforeShellExecution, 'command', scriptPath)
+}
+
+function globalCredentialGuardInstalledCopilot() {
+  const scriptPath = globalCredentialGuardScriptPath()
+  if (!scriptPath) return false
+  const root = readGlobalHookJSON('.copilot', 'settings.json')
+  if (!root || !root.hooks) return false
+  return hasEntry(root.hooks.preToolUse, 'bash', scriptPath)
+}
+
+/**
+ * ~/.kiro/hooks/trackfw-credential-guard.json is 100% dedicated to the
+ * global credential-guard wiring (overwritten wholesale, never merged), so
+ * presence + non-empty content is sufficient — matches the roadmap's
+ * explicit instruction for Kiro.
+ */
+function globalCredentialGuardInstalledKiro() {
+  const home = os.homedir()
+  if (!home) return false
+  try {
+    const stat = fs.statSync(path.join(home, '.kiro', 'hooks', 'trackfw-credential-guard.json'))
+    return stat.size > 0
+  } catch (_) {
+    return false
+  }
+}
 
 // ---------------------------------------------------------------------------
 // generateAttentionScripts — writes the two shell scripts to scripts/
@@ -145,13 +459,30 @@ 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.
+  if (!globalCredentialGuardInstalledClaude()) {
+    data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Bash', GUARD_CMD)
+  }
   data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'AskUserQuestion', CLEANUP_CMD)
+  if (!globalCredentialGuardInstalledClaude()) {
+    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'Bash', GUARD_CMD)
+  }
 
   writeJSON(filePath, data)
 }
 
 // ---------------------------------------------------------------------------
 // Codex — .codex/hooks.json
+//
+// Two independent hook events: PermissionRequest (matcher ".*") for the existing
+// attention-signal -- only fires when Codex is about to prompt for approval, not
+// for every command -- and PreToolUse/PostToolUse (matcher "Bash") for
+// credential-guard, which fires for every Bash tool call regardless of approval.
+// Confirmed against https://developers.openai.com/codex/hooks (2026-08-05): hooks
+// 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).
 // ---------------------------------------------------------------------------
 
 function injectCodexHooks(cwd) {
@@ -160,13 +491,38 @@ 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.
+  const skipCodexCG = globalCredentialGuardInstalledCodex()
+  if (!skipCodexCG) {
+    data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Bash', GUARD_CMD)
+  }
   data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, '.*', CLEANUP_CMD)
+  if (!skipCodexCG) {
+    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'Bash', GUARD_CMD)
+  }
 
   writeJSON(filePath, data)
 }
 
 // ---------------------------------------------------------------------------
 // Gemini — .gemini/settings.json
+//
+// Three independent hook events: Notification (matcher "ToolPermission") for the
+// existing attention-signal -- only fires when Gemini CLI is about to prompt for
+// permission, not for every tool call -- and BeforeTool/AfterTool (matcher
+// "run_shell_command") for credential-guard, which fires for every shell tool call
+// regardless of whether a permission prompt is needed. Confirmed against
+// https://geminicli.com/docs/hooks/reference (retrieved 2026-08-05): BeforeTool
+// "Fires before a tool is invoked. Used for argument validation, security checks,
+// and parameter rewriting" and supports "Exit Code 2 (Block Tool): Prevents
+// execution. Uses stderr as the reason" -- matching trackfw-credential-guard.sh's
+// existing "block" mode. The shell tool's canonical name is "run_shell_command"
+// (doc: "you can match any built-in tool (for example, read_file,
+// run_shell_command)"); matcher is a regex evaluated against tool_name. AfterTool
+// (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.
 // ---------------------------------------------------------------------------
 
 function injectGeminiHooks(cwd) {
@@ -175,75 +531,232 @@ 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
+  // 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.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, '*', CLEANUP_CMD)
+  if (!skipGeminiCG) {
+    data.hooks.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, 'run_shell_command', GUARD_CMD)
+  }
 
   writeJSON(filePath, data)
 }
 
 // ---------------------------------------------------------------------------
 // Kiro — .kiro/hooks/trackfw-attention.json (dedicated file, safe overwrite)
+//
+// Format confirmed against https://kiro.dev/docs/hooks/ , https://kiro.dev/docs/hooks/types and
+// https://kiro.dev/docs/hooks/actions/ (retrieved 2026-08-05). Top level is {"version": "v1", "hooks":
+// [...]} ("version" is the string "v1"), each entry {"name", "description"?, "trigger", "matcher"?,
+// "action", ...}. The field is "trigger" (NOT "event" as previously emitted here and in the Go/Python
+// siblings -- "event" does not exist in the documented schema). "matcher" is a plain regex string
+// matched against tool name for PreToolUse/PostToolUse (NOT an object like {tool_name: ".*"} as
+// previously emitted) -- "*" is the documented wildcard for "all tools"; ".*" is not a documented
+// matcher value. PreToolUse ("Before a tool is about to execute", Can block: Yes) is confirmed distinct
+// from PostFileSave/file-save events, resolving the ADR's open question about Kiro intercepting shell
+// commands pre-execution. Blocking contract: any non-zero exit from a PreToolUse command hook blocks
+// the tool invocation (stricter than the exit-code-2-specific contract of Claude Code/Codex/Gemini);
+// trackfw-credential-guard.sh only ever exits 0 or 2 on its normal-operation paths (ML-1A), so this is
+// safe. Shell tool matcher uses the documented alias "shell" ("all built-in shell command-related
+// tools"), broader than the single canonical tool id "execute_bash". This file is fully
+// generated/overwritten by trackfw (not merged with user content), so the legacy attention-signal/
+// cleanup entries are realigned to the correct schema here too rather than left in the old, never-valid
+// shape (same situation as the GitHub Copilot fix in ML-2D).
 // ---------------------------------------------------------------------------
 
 function injectKiroHooks(cwd) {
   const filePath = path.join(cwd, '.kiro', 'hooks', 'trackfw-attention.json')
-  const data = {
-    hooks: [
+  const hooks = [
+    {
+      name: 'trackfw-attention-signal',
+      description: 'Signals trackfw board when agent executes a tool',
+      trigger: 'PreToolUse',
+      matcher: '*',
+      action: { type: 'command', command: SIGNAL_CMD },
+    },
+    {
+      name: 'trackfw-attention-cleanup',
+      description: 'Clears trackfw board attention after tool completes',
+      trigger: 'PostToolUse',
+      matcher: '*',
+      action: { type: 'command', command: CLEANUP_CMD },
+    },
+  ]
+
+  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A): skip project-scope
+  // credential-guard entries when the global one is already installed.
+  if (!globalCredentialGuardInstalledKiro()) {
+    hooks.push(
       {
-        name: 'trackfw-attention-signal',
-        description: 'Signals trackfw board when agent executes a tool',
-        event: 'PreToolUse',
-        matcher: { tool_name: '.*' },
-        action: { type: 'command', command: SIGNAL_CMD },
+        name: 'trackfw-credential-guard-pre',
+        description: 'Blocks/warns on possible plaintext credential materialization before a shell command executes',
+        trigger: 'PreToolUse',
+        matcher: 'shell',
+        action: { type: 'command', command: GUARD_CMD },
       },
       {
-        name: 'trackfw-attention-cleanup',
-        description: 'Clears trackfw board attention after tool completes',
-        event: 'PostToolUse',
-        matcher: { tool_name: '.*' },
-        action: { type: 'command', command: CLEANUP_CMD },
+        name: 'trackfw-credential-guard-post',
+        description: 'Warns on possible plaintext credential materialization after a shell command executes',
+        trigger: 'PostToolUse',
+        matcher: 'shell',
+        action: { type: 'command', command: GUARD_CMD },
       },
-    ],
+    )
   }
+
+  const data = { version: 'v1', hooks }
   writeJSON(filePath, data)
 }
 
 // ---------------------------------------------------------------------------
 // Copilot — .github/hooks/trackfw-attention.json (dedicated file, safe overwrite)
+//
+// Format confirmed against https://docs.github.com/en/copilot/reference/hooks-reference (retrieved
+// 2026-08-05): repository-level hook files live at .github/hooks/*.json, using the schema
+// {"version": 1, "hooks": {"<event>": [<command entry>, ...]}}, where a command entry is
+// {"type": "command", "bash": "...", "cwd": "...", "timeoutSec": N}. This is the format
+// `inject_copilot_hooks` (Python) already used; the {"hooks": [{"event", "run"}]} shape this function
+// previously emitted does not match any format documented by GitHub -- this ML aligns Go/Node to
+// Python (which was correct) rather than the other way around.
+//
+// Matcher: the doc's matcher-filtering table lists `preToolUse -> toolName` and `postToolUse ->
+// toolName` (a regex, anchored `^(?:PATTERN)$`), and shows a worked `"matcher"` field inline on a
+// postToolUse command entry. With camelCase event names (preToolUse/postToolUse, used here), toolName
+// carries the runtime tool name, and the shell tool's runtime name is "bash" (lowercase) -- distinct
+// from PascalCase events, which report the Claude-mapped name "Bash". trackfw-credential-guard.sh
+// scans the raw JSON payload for JWT/AWS-key patterns regardless of field names (ML-1A), so it works
+// under either payload shape; the matcher below is a scope-narrowing optimization only.
+//
+// Concurrency: "If multiple hooks of the same type are configured, they execute in order" (same
+// section) -- Copilot hooks run serially, in configured order, for the same event, unlike Codex's
+// confirmed-concurrent or Gemini's undocumented cross-group model. The ML-1A fix (credential-guard's
+// "warn" mode writes to its own dedicated $ROADMAP_DIR/.trackfw-credential-guard.json, never touching
+// the shared .trackfw-attention.json that trackfw-attention-cleanup.sh deletes) makes ordering moot
+// regardless.
 // ---------------------------------------------------------------------------
 
 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.
+  if (!globalCredentialGuardInstalledCopilot()) {
+    preToolUse.push({ type: 'command', matcher: 'bash', bash: GUARD_CMD, cwd: '.', timeoutSec: 10 })
+    postToolUse.push({ type: 'command', matcher: 'bash', bash: GUARD_CMD, cwd: '.', timeoutSec: 10 })
+  }
+
   const data = {
-    hooks: [
-      {
-        event: 'preToolUse',
-        run: SIGNAL_CMD,
-      },
-      {
-        event: 'postToolUse',
-        run: CLEANUP_CMD,
-      },
-    ],
+    version: 1,
+    hooks: { preToolUse, postToolUse },
   }
   writeJSON(filePath, data)
 }
 
 // ---------------------------------------------------------------------------
 // Cursor — .cursor/hooks.json
+//
+// Two independent things are wired here, both nested under the real Cursor
+// hook config `{"version": 1, "hooks": {"<eventName>": [...] }}`:
+//   - hooks.preToolUse + hooks.postToolUse (migrated by this ML) --
+//     attention-signal/cleanup. Prior to this ML these were written to
+//     top-level preToolUse/postToolUse arrays, which did not match any
+//     documented Cursor event (confirmed 2026-08-05, see docs/cli-parity.md
+//     "Cursor wiring (ML-2E)"). Re-fetching https://cursor.com/docs/hooks on
+//     2026-08-06 (the /docs/agent/hooks URL now 308-redirects there) shows
+//     Cursor's docs were updated in the interim to add three new generic
+//     events: preToolUse/postToolUse/postToolUseFailure, "fires for all tool
+//     types (Shell, Read, Write, MCP, Task, etc.)". preToolUse's documented
+//     input is `{"tool_name","tool_input":{...},"tool_use_id","cwd",...}`
+//     and postToolUse's is the same shape plus `tool_output`/`duration` --
+//     structurally identical to Claude Code's PreToolUse/PostToolUse payload
+//     (`tool_name`/`tool_input`), which is exactly the shape
+//     scripts/trackfw-attention-signal.sh and trackfw-attention-cleanup.sh
+//     already parse (`.tool_name`, `.tool_input.question // .tool_input.command`).
+//     No script changes were needed. Per-hook `matcher` filters by tool type
+//     (e.g. "Shell|Read|Write") and is optional; intentionally omitted here,
+//     same reasoning as beforeShellExecution below -- the attention signal
+//     must fire for every tool use, not a filtered subset.
+//   - hooks.beforeShellExecution + hooks.afterShellExecution (ML-2E, prior
+//     cycle) -- credential-guard. beforeShellExecution is the real,
+//     Bash-specific, pre-execution event: input is
+//     `{"command","cwd","sandbox"}`, response (stdout JSON, only read on
+//     exit code 0) is `{"permission":"allow"|"deny"|"ask","user_message":"...",
+//     "agent_message":"..."}`. Per the documented "Exit code behavior": exit 0 uses the
+//     JSON output (or defaults to allow if stdout has none -- confirmed by the doc's own
+//     minimal example hook, which exits 0 with no stdout at all), exit 2 blocks the
+//     action ("equivalent to returning permission: \"deny\""), any other exit code
+//     fail-opens (hook failed, action proceeds). This is already exactly
+//     trackfw-credential-guard.sh's existing contract (block mode -> exit 2 + stderr, warn
+//     mode -> exit 0), so no script changes were needed to wire Cursor. afterShellExecution
+//     is a post-execution audit-only event (input adds "output"/"duration", no
+//     allow/deny/ask response defined) -- added in parallel for symmetry with the
+//     PostToolUse wiring already used for the other CLIs in this wave. Concurrency between
+//     hooks registered on the same event was not documented on the page retrieved for this
+//     investigation (unlike Codex, which explicitly documents concurrent execution); not
+//     assumed either way -- not a blocker here since this event array only ever contains
+//     the single credential-guard entry added by trackfw.
+//
+// Backward compatibility: a .cursor/hooks.json written by a pre-migration
+// trackfw still has the legacy top-level preToolUse/postToolUse arrays. This
+// function migrates known trackfw entries out of those top-level arrays into
+// the nested hooks.preToolUse/hooks.postToolUse location, and drops the
+// top-level key entirely once it is empty -- but never touches or deletes
+// unrelated entries a user may have added there themselves (those keys are
+// inert either way -- Cursor never read the top-level location -- so leaving
+// them is harmless and avoids destroying unrelated user data on a guess).
 // ---------------------------------------------------------------------------
 
+function removeKnownCommandFromLegacyTopLevelArray(data, key, command) {
+  if (!Array.isArray(data[key])) return
+  const kept = data[key].filter((item) => !(item && item.command === command))
+  if (kept.length === 0) {
+    delete data[key]
+  } else {
+    data[key] = kept
+  }
+}
+
 function injectCursorHooks(cwd) {
   const filePath = path.join(cwd, '.cursor', 'hooks.json')
   const data = readJSON(filePath)
 
-  if (!Array.isArray(data.preToolUse)) data.preToolUse = []
-  if (!hasEntry(data.preToolUse, 'command', SIGNAL_CMD)) {
-    data.preToolUse.push({ command: SIGNAL_CMD })
+  if (typeof data.version === 'undefined') data.version = 1
+  if (typeof data.hooks !== 'object' || data.hooks === null || Array.isArray(data.hooks)) {
+    data.hooks = {}
+  }
+
+  // Migrate any legacy top-level preToolUse/postToolUse trackfw entries
+  // (written by trackfw before this ML) into the nested, real hooks.
+  if (!Array.isArray(data.hooks.preToolUse)) data.hooks.preToolUse = []
+  if (!hasEntry(data.hooks.preToolUse, 'command', SIGNAL_CMD)) {
+    data.hooks.preToolUse.push({ command: SIGNAL_CMD })
   }
+  removeKnownCommandFromLegacyTopLevelArray(data, 'preToolUse', SIGNAL_CMD)
 
-  if (!Array.isArray(data.postToolUse)) data.postToolUse = []
-  if (!hasEntry(data.postToolUse, 'command', CLEANUP_CMD)) {
-    data.postToolUse.push({ command: CLEANUP_CMD })
+  if (!Array.isArray(data.hooks.postToolUse)) data.hooks.postToolUse = []
+  if (!hasEntry(data.hooks.postToolUse, 'command', CLEANUP_CMD)) {
+    data.hooks.postToolUse.push({ command: CLEANUP_CMD })
+  }
+  removeKnownCommandFromLegacyTopLevelArray(data, 'postToolUse', CLEANUP_CMD)
+
+  // Dedup (ROADMAP-2026-08-06 Wave 3/ML-3A): skip project-scope
+  // credential-guard entries when the global one is already installed.
+  if (!globalCredentialGuardInstalledCursor()) {
+    if (!Array.isArray(data.hooks.beforeShellExecution)) data.hooks.beforeShellExecution = []
+    if (!hasEntry(data.hooks.beforeShellExecution, 'command', GUARD_CMD)) {
+      data.hooks.beforeShellExecution.push({ command: GUARD_CMD })
+    }
+
+    if (!Array.isArray(data.hooks.afterShellExecution)) data.hooks.afterShellExecution = []
+    if (!hasEntry(data.hooks.afterShellExecution, 'command', GUARD_CMD)) {
+      data.hooks.afterShellExecution.push({ command: GUARD_CMD })
+    }
   }
 
   writeJSON(filePath, data)
@@ -316,6 +829,8 @@ function injectHooksDetected(cwd) {
 
 module.exports = {
   generateAttentionScripts,
+  generateCredentialGuardScript,
+  generateGlobalCredentialGuardScript,
   injectClaudeHooks,
   injectCodexHooks,
   injectGeminiHooks,
@@ -324,4 +839,7 @@ module.exports = {
   injectCursorHooks,
   injectWindsurfHooks,
   injectHooksDetected,
+  mergeClaudeHookArray,
+  mergeSimpleCommandArray,
+  mergeCopilotHookArray,
 }

package/src/generators/init.js

@@ -33,6 +33,7 @@ async function scaffold(cfg, cwd) {
   writeTrackfwConfig(cfg, root)
   generateValidateScript(cfg, root)
   generateAttentionScripts(cfg, root)
+  generateCredentialGuardScript(root)
   generateCIWorkflow(cfg, root)
   generateGitHooks(cfg, root)
   generateCommitMsgHook(cfg, root)
@@ -168,6 +169,11 @@ function generateAttentionScripts(cfg, cwd) {
   gen(cfg, cwd || process.cwd())
 }
 
+function generateCredentialGuardScript(cwd) {
+  const { generateCredentialGuardScript: gen } = require('./hooks')
+  gen(cwd || process.cwd())
+}
+
 function injectHooksDetected(cwd) {
   const { injectHooksDetected: inject } = require('./hooks')
   inject(cwd || process.cwd())
@@ -1322,6 +1328,7 @@ module.exports = {
   writeTrackfwConfig,
   generateValidateScript,
   generateAttentionScripts,
+  generateCredentialGuardScript,
   generateCIWorkflow,
   generateGitHooks,
   generateCommitMsgHook,