trackfw 6.7.0 → 6.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "6.7.0",
+  "version": "6.8.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/generators/hooks.js

@@ -85,6 +85,30 @@ function mergeClaudeHookArray(existing, matcher, command) {
   return arr
 }
 
+// migrateHookCommand rewrites a legacy hook command to a new one, in place, for every entry
+// matching the given matcher inside a "matcher + hooks[].command" shaped array -- the format
+// shared by Claude, Codex and Gemini's merge-based settings files (PreToolUse/PostToolUse/
+// PermissionRequest/Notification/BeforeTool/AfterTool). Used to fix settings files already written
+// by an older trackfw before a command string changes -- without this, re-running
+// `trackfw init`/`update` only ever appends the new (fixed) command alongside the stale one (merge
+// dedup in mergeClaudeHookArray keys on the exact command string, so it can't tell "same guard, new
+// path" from "a different hook"), leaving the broken entry in place to keep firing and failing
+// forever. Originally written for Claude only (hence the doc comment history); generalized
+// (ROADMAP-2026-08-11 ML-1A) so Codex/Gemini injectors can call it too, ahead of the
+// mechanism-specific string changes those CLIs' waves make. Must always be called before the
+// corresponding mergeClaudeHookArray call for the same matcher, or the merge's exact-string dedup
+// will append a duplicate instead of rewriting in place.
+function migrateHookCommand(existing, matcher, oldCommand, newCommand) {
+  const arr = Array.isArray(existing) ? existing : []
+  for (const item of arr) {
+    if (!item || item.matcher !== matcher) continue
+    const innerHooks = Array.isArray(item.hooks) ? item.hooks : []
+    for (const h of innerHooks) {
+      if (h && h.command === oldCommand) h.command = newCommand
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Scripts content
 // ---------------------------------------------------------------------------
@@ -416,9 +440,86 @@ function generateGlobalCredentialGuardScript(home) {
   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'
+// SIGNAL_CMD_*/CLEANUP_CMD_* — split per-CLI (ROADMAP-2026-08-11 ML-2A) from what used to be two
+// constants (SIGNAL_CMD/CLEANUP_CMD) shared by all 6 CLI injectors. Mutating a shared constant to
+// fix one CLI's path-resolution mechanism silently changed the emission of the other 5 -- Wave 0 of
+// that roadmap proved Cursor and Copilot are *already correct* (Cursor hooks run from the project
+// root; Copilot emits the native "cwd": "." field), so an accidental shared-constant edit there
+// would be a regression in verified-good wiring, not just scope creep. Each constant starts equal
+// to the pre-split literal; only the Claude ones (ML-2A, this change) move to the
+// $CLAUDE_PROJECT_DIR-pinned form below. GUARD_CMD was later split too (ML-3A) once Codex's guard
+// command needed to change -- see the GUARD_CMD_* block below.
+// ROADMAP-2026-08-11 ML-3A: Codex CLI does not expose a project-root env var for repo-local hooks
+// (unlike Claude's $CLAUDE_PROJECT_DIR or Gemini's $GEMINI_PROJECT_DIR) -- the only documented
+// mechanism is shell substitution. Per ADR-2026-08-11 ("Codex — alterar, com dependência explícita
+// de shell e git"), the command is wrapped in literal double quotes around
+// `$(git rev-parse --show-toplevel)`, matching every repo-local hook example in the official Codex
+// docs (https://developers.openai.com/codex/config-advanced): "For repo-local hooks, prefer
+// resolving from the git root instead of using a relative path such as `.codex/hooks/...`."
+const CODEX_ROOT = '"$(git rev-parse --show-toplevel)'
+
+const SIGNAL_CMD_CLAUDE = '$CLAUDE_PROJECT_DIR/scripts/trackfw-attention-signal.sh'
+const SIGNAL_CMD_CODEX = CODEX_ROOT + '/scripts/trackfw-attention-signal.sh"'
+// $GEMINI_PROJECT_DIR (ROADMAP-2026-08-11 ML-4A): distinct from the session-following
+// $GEMINI_CWD, documented and used in 100% of the Gemini CLI's official hook command
+// examples (ADR-2026-08-11, "Gemini CLI — alterar, por argumento de assimetria"). Expanded
+// by the Gemini CLI runtime itself -- no shell substitution needed, no literal quotes.
+const SIGNAL_CMD_GEMINI = '$GEMINI_PROJECT_DIR/scripts/trackfw-attention-signal.sh'
+const SIGNAL_CMD_KIRO = 'scripts/trackfw-attention-signal.sh'
+const SIGNAL_CMD_COPILOT = 'scripts/trackfw-attention-signal.sh'
+const SIGNAL_CMD_CURSOR = 'scripts/trackfw-attention-signal.sh'
+
+const CLEANUP_CMD_CLAUDE = '$CLAUDE_PROJECT_DIR/scripts/trackfw-attention-cleanup.sh'
+const CLEANUP_CMD_CODEX = CODEX_ROOT + '/scripts/trackfw-attention-cleanup.sh"'
+const CLEANUP_CMD_GEMINI = '$GEMINI_PROJECT_DIR/scripts/trackfw-attention-cleanup.sh'
+const CLEANUP_CMD_KIRO = 'scripts/trackfw-attention-cleanup.sh'
+const CLEANUP_CMD_COPILOT = 'scripts/trackfw-attention-cleanup.sh'
+const CLEANUP_CMD_CURSOR = 'scripts/trackfw-attention-cleanup.sh'
+
+// Pre-ML-2A literal value of SIGNAL_CMD_CLAUDE/CLEANUP_CMD_CLAUDE, kept only as the `oldCommand`
+// argument to the migration calls in injectClaudeHooks below (rewrites settings.json entries
+// written by a pre-ML-2A trackfw in place, mirroring the GUARD_CMD_CLAUDE migration pattern).
+const SIGNAL_CMD_CLAUDE_LEGACY = 'scripts/trackfw-attention-signal.sh'
+const CLEANUP_CMD_CLAUDE_LEGACY = 'scripts/trackfw-attention-cleanup.sh'
+
+// Pre-ML-3A literal value of SIGNAL_CMD_CODEX/CLEANUP_CMD_CODEX, kept only as the `oldCommand`
+// argument to the migration calls in injectCodexHooks below.
+const SIGNAL_CMD_CODEX_LEGACY = 'scripts/trackfw-attention-signal.sh'
+const CLEANUP_CMD_CODEX_LEGACY = 'scripts/trackfw-attention-cleanup.sh'
+
+// Pre-ML-4A literal value of SIGNAL_CMD_GEMINI/CLEANUP_CMD_GEMINI/GUARD_CMD_GEMINI, kept only as
+// the `oldCommand` argument to the migration calls in injectGeminiHooks below.
+const SIGNAL_CMD_GEMINI_LEGACY = 'scripts/trackfw-attention-signal.sh'
+const CLEANUP_CMD_GEMINI_LEGACY = 'scripts/trackfw-attention-cleanup.sh'
+const GUARD_CMD_GEMINI_LEGACY = 'scripts/trackfw-credential-guard.sh'
+
+// GUARD_CMD_* -- split per-CLI (ROADMAP-2026-08-11 ML-3A) from what used to be one constant
+// (GUARD_CMD) shared by Codex/Gemini/Kiro/Copilot/Cursor (Claude already had its own,
+// GUARD_CMD_CLAUDE, since ML-2A). Same rationale as the SIGNAL_CMD_*/CLEANUP_CMD_* split above:
+// Cursor and Copilot are verified-correct wiring (ML-0A), so a shared-constant edit made for Codex
+// would have silently regressed them. Each constant starts equal to the pre-split literal; only
+// GUARD_CMD_CODEX (this ML) moves to the new form below.
+// Legacy relative-path literal, pre-dating both the ML-2A Claude fix and the ML-3A Codex fix --
+// kept only as the `oldCommand` argument to migration calls (Claude's migration below, and Codex's
+// until this ML rewrites it), mirroring the SIGNAL_CMD_CLAUDE_LEGACY/CLEANUP_CMD_CLAUDE_LEGACY
+// pattern above.
+const GUARD_CMD_LEGACY = 'scripts/trackfw-credential-guard.sh'
+const GUARD_CMD_CODEX = CODEX_ROOT + '/scripts/trackfw-credential-guard.sh"'
+const GUARD_CMD_GEMINI = '$GEMINI_PROJECT_DIR/scripts/trackfw-credential-guard.sh'
+const GUARD_CMD_KIRO = 'scripts/trackfw-credential-guard.sh'
+const GUARD_CMD_COPILOT = 'scripts/trackfw-credential-guard.sh'
+const GUARD_CMD_CURSOR = 'scripts/trackfw-credential-guard.sh'
+
+// Claude Code only (2026-08-09 fix, reported in production against the CMDB project): Claude Code
+// resolves a bare relative hook command against the hook's *dynamic* cwd (tracks `cd`s the agent
+// runs during the session), not the project root -- confirmed against
+// https://code.claude.com/docs/en/hooks: "Handlers run in the current directory... cwd is dynamic".
+// Any Bash/Read/Write/Edit call after the agent `cd`s into a subdirectory (e.g. a monorepo package)
+// made the hook fail with "No such file or directory". $CLAUDE_PROJECT_DIR is the env var Claude
+// Code guarantees stays pinned to the project root regardless of cwd drift (same doc) -- used here
+// instead of GUARD_CMD, matching the pattern this project's own custom hooks already relied on
+// successfully in practice.
+const GUARD_CMD_CLAUDE = '$CLAUDE_PROJECT_DIR/scripts/trackfw-credential-guard.sh'
 
 // ---------------------------------------------------------------------------
 // Global credential-guard dedup (ROADMAP-2026-08-06 Wave 3/ML-3A)
@@ -551,22 +652,41 @@ function injectClaudeHooks(cwd) {
   const data = readJSON(filePath)
 
   if (!data.hooks) data.hooks = {}
-  data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'AskUserQuestion', SIGNAL_CMD)
+
+  // Migration (ROADMAP-2026-08-11 ML-2A): rewrite any stale relative-path attention-signal/cleanup
+  // command from an older trackfw run before merging the $CLAUDE_PROJECT_DIR-pinned one below, so
+  // upgrading doesn't just append a second, still-cwd-fragile entry alongside the fixed one (same
+  // "No such file or directory" bug class as the credential-guard fix below, and the same
+  // migrate-before-merge ordering requirement -- mergeClaudeHookArray's dedup keys on the exact
+  // command string, so it can't tell "same hook, new path" from "a different hook").
+  migrateHookCommand(data.hooks.PreToolUse, 'AskUserQuestion', SIGNAL_CMD_CLAUDE_LEGACY, SIGNAL_CMD_CLAUDE)
+  migrateHookCommand(data.hooks.PostToolUse, 'AskUserQuestion', CLEANUP_CMD_CLAUDE_LEGACY, CLEANUP_CMD_CLAUDE)
+
+  data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'AskUserQuestion', SIGNAL_CMD_CLAUDE)
+
+  // Rewrite any stale relative-path credential-guard command from an older trackfw run before
+  // merging the fixed one below, so upgrading doesn't just append a second, still-broken entry
+  // alongside the new one (see GUARD_CMD_CLAUDE comment for the "No such file or directory" bug).
+  for (const matcher of ['Bash', 'Read', 'Write|Edit']) {
+    migrateHookCommand(data.hooks.PreToolUse, matcher, GUARD_CMD_LEGACY, GUARD_CMD_CLAUDE)
+    migrateHookCommand(data.hooks.PostToolUse, matcher, GUARD_CMD_LEGACY, GUARD_CMD_CLAUDE)
+  }
+
   // 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)
+    data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Bash', GUARD_CMD_CLAUDE)
     // 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.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Read', GUARD_CMD_CLAUDE)
+    data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Write|Edit', GUARD_CMD_CLAUDE)
   }
-  data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'AskUserQuestion', CLEANUP_CMD)
+  data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'AskUserQuestion', CLEANUP_CMD_CLAUDE)
   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)
+    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'Bash', GUARD_CMD_CLAUDE)
+    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'Read', GUARD_CMD_CLAUDE)
+    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'Write|Edit', GUARD_CMD_CLAUDE)
   }
 
   writeJSON(filePath, data)
@@ -596,19 +716,30 @@ function injectCodexHooks(cwd) {
   const data = readJSON(filePath)
 
   if (!data.hooks) data.hooks = {}
-  data.hooks.PermissionRequest = mergeClaudeHookArray(data.hooks.PermissionRequest, '.*', SIGNAL_CMD)
+
+  // Migration wiring (ROADMAP-2026-08-11 ML-1A, strings updated in ML-3A): rewrites any stale
+  // relative-path entry from before this fix in place, so `trackfw update` doesn't just append the
+  // new $(git rev-parse ...) entry alongside the still-cwd-fragile old one.
+  migrateHookCommand(data.hooks.PermissionRequest, '.*', SIGNAL_CMD_CODEX_LEGACY, SIGNAL_CMD_CODEX)
+  migrateHookCommand(data.hooks.PreToolUse, 'Bash', GUARD_CMD_LEGACY, GUARD_CMD_CODEX)
+  migrateHookCommand(data.hooks.PreToolUse, 'apply_patch', GUARD_CMD_LEGACY, GUARD_CMD_CODEX)
+  migrateHookCommand(data.hooks.PostToolUse, '.*', CLEANUP_CMD_CODEX_LEGACY, CLEANUP_CMD_CODEX)
+  migrateHookCommand(data.hooks.PostToolUse, 'Bash', GUARD_CMD_LEGACY, GUARD_CMD_CODEX)
+  migrateHookCommand(data.hooks.PostToolUse, 'apply_patch', GUARD_CMD_LEGACY, GUARD_CMD_CODEX)
+
+  data.hooks.PermissionRequest = mergeClaudeHookArray(data.hooks.PermissionRequest, '.*', SIGNAL_CMD_CODEX)
   // 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.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'Bash', GUARD_CMD_CODEX)
+    data.hooks.PreToolUse = mergeClaudeHookArray(data.hooks.PreToolUse, 'apply_patch', GUARD_CMD_CODEX)
   }
-  data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, '.*', CLEANUP_CMD)
+  data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, '.*', CLEANUP_CMD_CODEX)
   if (!skipCodexCG) {
-    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'Bash', GUARD_CMD)
-    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'apply_patch', GUARD_CMD)
+    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'Bash', GUARD_CMD_CODEX)
+    data.hooks.PostToolUse = mergeClaudeHookArray(data.hooks.PostToolUse, 'apply_patch', GUARD_CMD_CODEX)
   }
 
   writeJSON(filePath, data)
@@ -645,21 +776,36 @@ function injectGeminiHooks(cwd) {
   const data = readJSON(filePath)
 
   if (!data.hooks) data.hooks = {}
-  data.hooks.Notification = mergeClaudeHookArray(data.hooks.Notification, 'ToolPermission', SIGNAL_CMD)
+
+  // Migration wiring (ROADMAP-2026-08-11 ML-1A): old === new is a functional no-op today, but
+  // proves the call point exists and runs before the merge below. The wave that changes the
+  // Gemini command strings (ML-4A) updates the oldCommand argument here instead of adding this
+  // call from scratch -- without it, the merge's exact-string dedup would append a duplicate
+  // alongside the stale entry.
+  migrateHookCommand(data.hooks.Notification, 'ToolPermission', SIGNAL_CMD_GEMINI_LEGACY, SIGNAL_CMD_GEMINI)
+  migrateHookCommand(data.hooks.BeforeTool, 'run_shell_command', GUARD_CMD_GEMINI_LEGACY, GUARD_CMD_GEMINI)
+  migrateHookCommand(data.hooks.BeforeTool, 'read_file|read_many_files', GUARD_CMD_GEMINI_LEGACY, GUARD_CMD_GEMINI)
+  migrateHookCommand(data.hooks.BeforeTool, 'write_file|replace', GUARD_CMD_GEMINI_LEGACY, GUARD_CMD_GEMINI)
+  migrateHookCommand(data.hooks.AfterTool, '*', CLEANUP_CMD_GEMINI_LEGACY, CLEANUP_CMD_GEMINI)
+  migrateHookCommand(data.hooks.AfterTool, 'run_shell_command', GUARD_CMD_GEMINI_LEGACY, GUARD_CMD_GEMINI)
+  migrateHookCommand(data.hooks.AfterTool, 'read_file|read_many_files', GUARD_CMD_GEMINI_LEGACY, GUARD_CMD_GEMINI)
+  migrateHookCommand(data.hooks.AfterTool, 'write_file|replace', GUARD_CMD_GEMINI_LEGACY, GUARD_CMD_GEMINI)
+
+  data.hooks.Notification = mergeClaudeHookArray(data.hooks.Notification, 'ToolPermission', SIGNAL_CMD_GEMINI)
   // 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.BeforeTool = mergeClaudeHookArray(data.hooks.BeforeTool, 'run_shell_command', GUARD_CMD_GEMINI)
+    data.hooks.BeforeTool = mergeClaudeHookArray(data.hooks.BeforeTool, 'read_file|read_many_files', GUARD_CMD_GEMINI)
+    data.hooks.BeforeTool = mergeClaudeHookArray(data.hooks.BeforeTool, 'write_file|replace', GUARD_CMD_GEMINI)
   }
-  data.hooks.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, '*', CLEANUP_CMD)
+  data.hooks.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, '*', CLEANUP_CMD_GEMINI)
   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)
+    data.hooks.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, 'run_shell_command', GUARD_CMD_GEMINI)
+    data.hooks.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, 'read_file|read_many_files', GUARD_CMD_GEMINI)
+    data.hooks.AfterTool = mergeClaudeHookArray(data.hooks.AfterTool, 'write_file|replace', GUARD_CMD_GEMINI)
   }
 
   writeJSON(filePath, data)
@@ -695,14 +841,14 @@ function injectKiroHooks(cwd) {
       description: 'Signals trackfw board when agent executes a tool',
       trigger: 'PreToolUse',
       matcher: '*',
-      action: { type: 'command', command: SIGNAL_CMD },
+      action: { type: 'command', command: SIGNAL_CMD_KIRO },
     },
     {
       name: 'trackfw-attention-cleanup',
       description: 'Clears trackfw board attention after tool completes',
       trigger: 'PostToolUse',
       matcher: '*',
-      action: { type: 'command', command: CLEANUP_CMD },
+      action: { type: 'command', command: CLEANUP_CMD_KIRO },
     },
   ]
 
@@ -716,14 +862,14 @@ function injectKiroHooks(cwd) {
         description: 'Blocks/warns on possible plaintext credential materialization before a shell command executes',
         trigger: 'PreToolUse',
         matcher: 'shell',
-        action: { type: 'command', command: GUARD_CMD },
+        action: { type: 'command', command: GUARD_CMD_KIRO },
       },
       {
         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 },
+        action: { type: 'command', command: GUARD_CMD_KIRO },
       },
       // 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.
@@ -732,28 +878,28 @@ function injectKiroHooks(cwd) {
         description: 'Blocks/warns on possible plaintext credential materialization before a file read',
         trigger: 'PreToolUse',
         matcher: 'read',
-        action: { type: 'command', command: GUARD_CMD },
+        action: { type: 'command', command: GUARD_CMD_KIRO },
       },
       {
         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 },
+        action: { type: 'command', command: GUARD_CMD_KIRO },
       },
       {
         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 },
+        action: { type: 'command', command: GUARD_CMD_KIRO },
       },
       {
         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 },
+        action: { type: 'command', command: GUARD_CMD_KIRO },
       },
     )
   }
@@ -797,19 +943,19 @@ function injectKiroHooks(cwd) {
 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 }]
+  const preToolUse = [{ type: 'command', bash: SIGNAL_CMD_COPILOT, cwd: '.', timeoutSec: 10 }]
+  const postToolUse = [{ type: 'command', bash: CLEANUP_CMD_COPILOT, cwd: '.', timeoutSec: 10 }]
 
   // 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 })
+    preToolUse.push({ type: 'command', matcher: 'bash', bash: GUARD_CMD_COPILOT, cwd: '.', timeoutSec: 10 })
+    preToolUse.push({ type: 'command', matcher: 'view', bash: GUARD_CMD_COPILOT, cwd: '.', timeoutSec: 10 })
+    preToolUse.push({ type: 'command', matcher: 'create|edit', bash: GUARD_CMD_COPILOT, cwd: '.', timeoutSec: 10 })
+    postToolUse.push({ type: 'command', matcher: 'bash', bash: GUARD_CMD_COPILOT, cwd: '.', timeoutSec: 10 })
+    postToolUse.push({ type: 'command', matcher: 'view', bash: GUARD_CMD_COPILOT, cwd: '.', timeoutSec: 10 })
+    postToolUse.push({ type: 'command', matcher: 'create|edit', bash: GUARD_CMD_COPILOT, cwd: '.', timeoutSec: 10 })
   }
 
   const data = {
@@ -895,29 +1041,29 @@ function injectCursorHooks(cwd) {
   // 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 })
+  if (!hasEntry(data.hooks.preToolUse, 'command', SIGNAL_CMD_CURSOR)) {
+    data.hooks.preToolUse.push({ command: SIGNAL_CMD_CURSOR })
   }
-  removeKnownCommandFromLegacyTopLevelArray(data, 'preToolUse', SIGNAL_CMD)
+  removeKnownCommandFromLegacyTopLevelArray(data, 'preToolUse', SIGNAL_CMD_CURSOR)
 
   if (!Array.isArray(data.hooks.postToolUse)) data.hooks.postToolUse = []
-  if (!hasEntry(data.hooks.postToolUse, 'command', CLEANUP_CMD)) {
-    data.hooks.postToolUse.push({ command: CLEANUP_CMD })
+  if (!hasEntry(data.hooks.postToolUse, 'command', CLEANUP_CMD_CURSOR)) {
+    data.hooks.postToolUse.push({ command: CLEANUP_CMD_CURSOR })
   }
-  removeKnownCommandFromLegacyTopLevelArray(data, 'postToolUse', CLEANUP_CMD)
+  removeKnownCommandFromLegacyTopLevelArray(data, 'postToolUse', CLEANUP_CMD_CURSOR)
 
   // 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 = []
-    if (!hasEntry(data.hooks.beforeShellExecution, 'command', GUARD_CMD)) {
-      data.hooks.beforeShellExecution.push({ command: GUARD_CMD })
+    if (!hasEntry(data.hooks.beforeShellExecution, 'command', GUARD_CMD_CURSOR)) {
+      data.hooks.beforeShellExecution.push({ command: GUARD_CMD_CURSOR })
     }
 
     if (!Array.isArray(data.hooks.afterShellExecution)) data.hooks.afterShellExecution = []
-    if (!hasEntry(data.hooks.afterShellExecution, 'command', GUARD_CMD)) {
-      data.hooks.afterShellExecution.push({ command: GUARD_CMD })
+    if (!hasEntry(data.hooks.afterShellExecution, 'command', GUARD_CMD_CURSOR)) {
+      data.hooks.afterShellExecution.push({ command: GUARD_CMD_CURSOR })
     }
 
     // Read/Write coverage (ADR-2026-08-06 emenda 7, 2026-08-08): wired via the generic
@@ -928,19 +1074,19 @@ function injectCursorHooks(cwd) {
     // 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)
+      Array.isArray(arr) && arr.some(e => e && e.command === GUARD_CMD_CURSOR && e.matcher === matcher)
 
     if (!hasGuardMatcherEntry(data.hooks.preToolUse, 'Read')) {
-      data.hooks.preToolUse.push({ command: GUARD_CMD, matcher: 'Read' })
+      data.hooks.preToolUse.push({ command: GUARD_CMD_CURSOR, matcher: 'Read' })
     }
     if (!hasGuardMatcherEntry(data.hooks.preToolUse, 'Write')) {
-      data.hooks.preToolUse.push({ command: GUARD_CMD, matcher: 'Write' })
+      data.hooks.preToolUse.push({ command: GUARD_CMD_CURSOR, matcher: 'Write' })
     }
     if (!hasGuardMatcherEntry(data.hooks.postToolUse, 'Read')) {
-      data.hooks.postToolUse.push({ command: GUARD_CMD, matcher: 'Read' })
+      data.hooks.postToolUse.push({ command: GUARD_CMD_CURSOR, matcher: 'Read' })
     }
     if (!hasGuardMatcherEntry(data.hooks.postToolUse, 'Write')) {
-      data.hooks.postToolUse.push({ command: GUARD_CMD, matcher: 'Write' })
+      data.hooks.postToolUse.push({ command: GUARD_CMD_CURSOR, matcher: 'Write' })
     }
   }