trackfw 7.5.0 → 7.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "7.5.0",
+  "version": "7.6.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/barrier.js

@@ -471,73 +471,137 @@ function evalAcceptanceEvidence(mls) {
 // roadmapTrustForGates determines whether the gates declared in a roadmap can
 // be trusted for execution without --trust-local-gates.
 //
-// Decision (AC4, AC11): the discriminant is git — a roadmap whose content
-// differs from origin/main, or that is absent from origin/main, is untrusted.
+// Posture (AC1): CLOSED by default. Gates execute only when the function can
+// PROVE that the roadmap is present in refs/remotes/origin/main byte-for-byte.
+// Absence of proof is absence of trust — every error path returns
+// { trusted: false } with a named failureMsg (AC2). Exactly one
+// { trusted: true } return, at the very end, after all proofs succeed.
 //
-// Returns { trusted: true } or { trusted: false, failureMsg: '...' }.
-// Fail-open when not in a git repo, origin/main not resolvable, or any git
-// error other than "path absent from origin/main". See docs/cli-parity.md.
-function roadmapTrustForGates(roadmapPath) {
+// AC3: the discriminant never parses git stderr. Steps 4 and 5 use
+// "git rev-parse --verify" and "git cat-file -e" whose exit codes answer
+// the questions directly. The fully-qualified ref refs/remotes/origin/main
+// is used throughout to prevent a local branch named "origin/main" from
+// satisfying the trust anchor.
+//
+// Residual (declared in docs/cli-parity.md): Windows users with
+// core.autocrlf=true may receive "content differs" for an otherwise-identical
+// roadmap (LF vs CRLF). The check fails closed, so the residual is safe.
+// roadmapTrustForGates determines whether the gates declared in a roadmap can
+// be trusted for execution without --trust-local-gates.
+//
+// localContentBuf (Buffer) is the content already read by the caller — the same
+// bytes used to parse gate commands. Comparing it here ensures the proof covers
+// exactly what executes (F1 invariant: what is proved = what executes).
+// The only remaining route from unverified bytes to sh -c is --trust-local-gates,
+// which requires explicit operator consent.
+function roadmapTrustForGates(roadmapPath, localContentBuf) {
   const roadmapDir = path.dirname(roadmapPath)
 
   // Step 1: check if we are inside a git repository.
+  // Two distinct failure reasons are separated here (F5):
+  //   revParse.error   → git binary not found in PATH (spawn failure)
+  //   revParse.status  → git ran but not inside a git repository
   const revParse = spawnSync('git', ['rev-parse', '--git-dir'], {
     cwd: roadmapDir,
     encoding: 'utf8',
     stdio: 'pipe',
   })
+  if (revParse.error) {
+    // Spawn failure: git binary is not installed or not in PATH.
+    return {
+      trusted: false,
+      failureMsg: 'gates not evaluated: git not found in PATH — install git to evaluate local gates',
+    }
+  }
   if (revParse.status !== 0) {
-    // Not a git repo → fail-open.
-    return { trusted: true }
+    return {
+      trusted: false,
+      failureMsg: 'gates not evaluated: not a git repository — pass --trust-local-gates to evaluate local gates',
+    }
   }
 
   // Step 2: get the repository toplevel.
-  const topLevel = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+  const topResult = spawnSync('git', ['rev-parse', '--show-toplevel'], {
     cwd: roadmapDir,
     encoding: 'utf8',
     stdio: 'pipe',
   })
-  if (topLevel.status !== 0) {
-    return { trusted: true }
+  if (topResult.status !== 0 || topResult.error) {
+    return {
+      trusted: false,
+      failureMsg: 'gates not evaluated: cannot resolve git repository root — pass --trust-local-gates to evaluate local gates',
+    }
   }
-  const repoRoot = topLevel.stdout.trim()
+  const repoRoot = topResult.stdout.trim()
 
   // Step 3: compute repo-relative path (always forward slashes for git).
   const absRoadmap = path.resolve(roadmapPath)
   const relPath = path.relative(repoRoot, absRoadmap).split(path.sep).join('/')
 
-  // Step 4: retrieve the file at origin/main.
-  const show = spawnSync('git', ['show', `origin/main:${relPath}`], {
+  // Step 4: verify that refs/remotes/origin/main resolves to a commit (AC3 —
+  // exit code only, no stderr parsing). Failure means: no remote named origin,
+  // origin/main never fetched, or wrong default branch name. All are untrusted.
+  const verify = spawnSync(
+    'git', ['rev-parse', '--verify', '--quiet', 'refs/remotes/origin/main^{commit}'],
+    { cwd: repoRoot, encoding: 'utf8', stdio: 'pipe' }
+  )
+  if (verify.status !== 0 || verify.error) {
+    return {
+      trusted: false,
+      failureMsg: 'gates not evaluated: origin/main ref not available — pass --trust-local-gates to evaluate local gates',
+    }
+  }
+
+  // Step 5: check whether the roadmap path exists in refs/remotes/origin/main
+  // (AC3 — "git cat-file -e" exits non-zero when the object does not exist).
+  const refPath = `refs/remotes/origin/main:${relPath}`
+  const catFile = spawnSync('git', ['cat-file', '-e', refPath], {
     cwd: repoRoot,
     encoding: 'utf8',
     stdio: 'pipe',
   })
-  if (show.status !== 0) {
-    // If the path specifically does not exist in origin/main → untrusted.
-    const stderr = show.stderr || ''
-    if (stderr.includes('does not exist in') || stderr.includes('exists on disk, but not in')) {
-      return {
-        trusted: false,
-        failureMsg: 'gates not evaluated: roadmap is not committed in origin/main — pass --trust-local-gates to evaluate local gates',
-      }
+  if (catFile.status !== 0 || catFile.error) {
+    return {
+      trusted: false,
+      failureMsg: 'gates not evaluated: roadmap is not committed in origin/main — pass --trust-local-gates to evaluate local gates',
     }
-    // Other failures (no remote, not fetched) → fail-open.
-    return { trusted: true }
   }
 
-  // Step 5: compare content byte-for-byte.
-  let localContent
-  try {
-    localContent = fs.readFileSync(roadmapPath, 'utf8')
-  } catch (_) {
-    return { trusted: true }
+  // Step 6: retrieve the file content from refs/remotes/origin/main.
+  // No encoding option → stdout is a Buffer for true byte-for-byte comparison (F4).
+  const show = spawnSync('git', ['show', refPath], {
+    cwd: repoRoot,
+    stdio: 'pipe',
+  })
+  if (show.status !== 0 || show.error) {
+    // The cat-file check already confirmed the object exists; this is an
+    // unexpected failure (e.g. transient I/O). Still fail closed.
+    return {
+      trusted: false,
+      failureMsg: 'gates not evaluated: cannot read roadmap from origin/main — pass --trust-local-gates to evaluate local gates',
+    }
   }
-  if (show.stdout !== localContent) {
+
+  // Step 7: compare content byte-for-byte.
+  // localContentBuf (the parameter) is the Buffer the caller already read — it
+  // is the same slice used to parse gate commands. No second read is performed
+  // here; the proof covers exactly what executes (F1 invariant).
+  // show.stdout is also a Buffer (no encoding option above) — true binary comparison (F4).
+  //
+  // Step 5 triple note (F5 — declared unseparable): git cat-file -e exits non-zero
+  // for (a) roadmap absent from origin/main, (b) relPath wrong (e.g. macOS symlink,
+  // mitigated by WORK_PHYS in check-barrier.sh), (c) unexpected I/O error. All are
+  // equally fail-closed; separating them without additional git invocations would
+  // expand the attack surface. Declared unseparable by design.
+  if (!localContentBuf.equals(show.stdout)) {
     return {
       trusted: false,
       failureMsg: 'gates not evaluated: roadmap content differs from origin/main — pass --trust-local-gates to evaluate local gates',
     }
   }
+
+  // Proven: roadmap is present in refs/remotes/origin/main and byte-identical.
+  // The buffer compared is the same one parsed for gate commands.
   return { trusted: true }
 }
 
@@ -548,8 +612,10 @@ function roadmapTrustForGates(roadmapPath) {
 const SH_MISSING_MSG =
   'gates not evaluated: sh not found in PATH — install a POSIX shell (e.g. Git Bash, WSL) to evaluate gates'
 
-function evalGates(commands, cwd, trustResult = { trusted: true }) {
+function evalGates(commands, cwd, trustResult = { trusted: false }) {
   // trustResult: { trusted: true } | { trusted: false, failureMsg: string }
+  // Default is { trusted: false } — fail-closed (F2). Every call site must pass
+  // an explicit trustResult; omitting it produces not_evaluated, not gate execution.
   if (!trustResult.trusted) {
     // Roadmap is not trusted: do not execute gates (AC3, AC14).
     // Report as not_evaluated — distinct from passed and blocked (AC6).
@@ -669,7 +735,10 @@ async function runBarrier(roadmapArg, waveOption, jsonOutput, trustLocalGates) {
 
   const cfg = config.load()
   const resolved = resolveRoadmapFile(cfg, roadmapArg)
-  const content = fs.readFileSync(resolved.path, 'utf8')
+  // Read as Buffer (no encoding) so the same bytes can be passed to roadmapTrustForGates
+  // for the byte-for-byte comparison (F1 invariant: what is proved = what executes).
+  const contentBuf = fs.readFileSync(resolved.path)
+  const content = contentBuf.toString('utf8')
   const lines = splitRoadmapLines(content)
 
   const startedAt = new Date()
@@ -678,9 +747,10 @@ async function runBarrier(roadmapArg, waveOption, jsonOutput, trustLocalGates) {
   const gates = parseGates(lines, wave.startLine, wave.endLine)
 
   // Determine trust for gate execution (AC11, AC12).
+  // Pass contentBuf so the trust check compares the same buffer parsed for gates.
   const trustResult = trustLocalGates
     ? { trusted: true }
-    : roadmapTrustForGates(resolved.path)
+    : roadmapTrustForGates(resolved.path, contentBuf)
 
   const checks = []
   checks.push(evalMlsComplete(mls, waveLabel))

package/src/commands/branch.js

@@ -30,8 +30,10 @@ function createBranchCommand() {
       "  4. With a match (or for chore/docs): runs 'git checkout -b <type>/<slug>', propagating\n" +
       "     Git's own output and exit status literally.\n\n" +
       'Create the governance artifacts first if this blocks you:\n' +
-      '  trackfw req new "title"\n' +
-      '  trackfw roadmap new "title"\n' +
+      '  trackfw req new "title"               # flat project\n' +
+      '  trackfw req new --agent <agent> "title"  # by_agent project with 2+ agents\n' +
+      '  trackfw roadmap new "title"               # flat project\n' +
+      '  trackfw roadmap new --agent <agent> "title"  # by_agent project with 2+ agents\n' +
       '  trackfw roadmap move <name> wip'
     )
     .argument('<spec>', '<type>/<slug>, type in feat, fix, refactor, chore, docs')

package/src/commands/commit.js

@@ -34,8 +34,10 @@ function createCommitCommand() {
       'ready-to-use message; review and edit before using it with -m. When \'--suggest\' is set,\n' +
       "'-m' (if also passed) is ignored and no commit ever happens.\n\n" +
       'Create the governance artifacts first if this blocks you:\n' +
-      '  trackfw req new "title"\n' +
-      '  trackfw roadmap new "title"\n' +
+      '  trackfw req new "title"               # flat project\n' +
+      '  trackfw req new --agent <agent> "title"  # by_agent project with 2+ agents\n' +
+      '  trackfw roadmap new "title"               # flat project\n' +
+      '  trackfw roadmap new --agent <agent> "title"  # by_agent project with 2+ agents\n' +
       '  trackfw roadmap move <name> wip'
     )
     .option('-m, --message <msg>', 'Commit message (required)')

package/src/commands/req.js

@@ -11,7 +11,8 @@ cmd.description(t('req.description'))
 
 cmd.command('new <title>')
   .description(t('req.new.description'))
-  .action(async (title) => {
+  .option('--agent <name>', 'Agent namespace to write the REQ into (required in by_agent with multiple namespaces)')
+  .action(async (title, opts) => {
     const { input, select } = require('@inquirer/prompts')
     const generators = require('../generators/req')
     const adrGenerators = require('../generators/adr')
@@ -68,7 +69,7 @@ cmd.command('new <title>')
       content.dependsOnADRs = [...new Set(generatedADRs)]
     }
 
-    await generators.newREQ(content)
+    await generators.newREQ(content, opts.agent)
 
     if (content.dependsOnADRs.length > 0) {
       console.log(`\n${t('req.new.adrDraftsCreated')}`)

package/src/commands/roadmap.js

@@ -12,14 +12,15 @@ cmd.command('new')
   .option('-t, --title <title>', 'Roadmap title (alias)')
   .option('-r, --req <path>', 'Path to the linked REQ')
   .option('--from-req <path>', 'Generate roadmap with ML stubs from REQ acceptance criteria')
+  .option('--agent <name>', 'Agent namespace to write the roadmap into (required in by_agent with multiple namespaces)')
   .action(async (titleArg, opts) => {
     if (opts.fromReq) {
-      newRoadmapFromReq(opts.fromReq)
+      newRoadmapFromReq(opts.fromReq, opts.agent)
       return
     }
     const title = titleArg || opts.title || 'New Roadmap'
     const reqPath = opts.req || ''
-    newRoadmap(title, reqPath)
+    newRoadmap(title, reqPath, opts.agent)
   })
 
 cmd.command('list')

package/src/commands/serve.js

@@ -13,6 +13,18 @@ const { handleAttention } = require('../serve/api_attention')
 
 const STATIC_DIR = path.join(__dirname, '..', 'serve', 'static')
 
+// REAL_STATIC_DIR é a versão canônica (symlinks resolvidos) de STATIC_DIR.
+// Calculado uma vez no carregamento do módulo para canonicalizar ambos os lados
+// na verificação de segurança do serveStatic (M-03: prevenção de escape via symlink).
+// Se STATIC_DIR não existir no momento do carregamento, fica null e serveStatic
+// retorna 404 para qualquer requisição de asset estático.
+let REAL_STATIC_DIR
+try {
+  REAL_STATIC_DIR = fs.realpathSync.native(STATIC_DIR)
+} catch (_) {
+  REAL_STATIC_DIR = null
+}
+
 // Aviso pinado, byte-idêntico entre os 3 runtimes (Go, Node.js, Python) — ver
 // docs/cli-parity.md "`trackfw serve` — endereço de escuta, `--host` e
 // aviso de exposição". Emitido quando --host resolve para uma interface
@@ -55,6 +67,73 @@ function displayUrl(host, port) {
   return `http://${host}:${port}`
 }
 
+// isValidHost reports whether host is acceptable as a --host argument.
+// Accepts: 'localhost', valid IPv4, valid IPv6 literal (without zone ID),
+// RFC-1123 hostname. Rejects anything else — in particular strings with shell
+// metacharacters, or IPv6 scoped addresses (zone ID after '%').
+//
+// Zone IDs are rejected even when syntactically clean (e.g. 'fe80::1%eth0')
+// because: (1) Go's net.ParseIP rejects them — parity requires all 3 CLIs to
+// agree; (2) Python's ipaddress.ip_address() accepts any zone ID content,
+// including cmd.exe metacharacters that list2cmdline does not quote; blocking
+// '%' aligns both runtimes and closes the entire attack class rather than
+// enumerating individual metacharacters.
+//
+// Espelha internal/serve/serve.go IsValidHost e _is_valid_host do Python.
+function isValidHost(host) {
+  if (host === 'localhost') return true
+  // Reject IPv6 scoped addresses (zone ID): '%' in host means a zone
+  // identifier that Python's ipaddress accepts with any content (including
+  // cmd.exe metacharacters); Go rejects all scoped addresses; rejecting here
+  // makes all three runtimes agree on the same contract.
+  if (host.includes('%')) return false
+  const net = require('net')
+  if (net.isIPv4(host) || net.isIPv6(host)) return true
+  // RFC 1123 hostname: labels separated by dots, each [a-zA-Z0-9] or hyphens,
+  // starting and ending with alphanum. Max label length 63, total max 253.
+  if (host.length > 253) return false
+  return /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/.test(host)
+}
+
+// browserArgv returns [cmd, args] for opening url in the default browser
+// without shell interpolation — argv, never a shell string. This is the only
+// safe form: exec(`open "${url}"`) interpolates url into a shell command and
+// allows injection when url contains shell metacharacters.
+//
+// Darwin / Linux: 'open' / 'xdg-open' are invoked directly; no shell involved.
+// Windows: spawn('cmd', ['/c', 'start', '', url]) passes url as a distinct
+// argv element to CreateProcess — safer than exec(), but cmd.exe still
+// re-parses its own metacharacters (& | ^ >) in the url portion. Defense for
+// that residual is AC4 (isValidHost) rejecting metacharacter-bearing hosts
+// before they reach this function.
+//
+// Exported for testing.
+function browserArgv(platform, url) {
+  if (platform === 'darwin') return ['open', [url]]
+  if (platform === 'win32') return ['cmd', ['/c', 'start', '', url]]
+  return ['xdg-open', [url]]
+}
+
+// openBrowser opens url in the default browser using spawn (argv, no shell).
+// Exported for testing with a PATH shim.
+//
+// Preserves the original UX: warn when the opener exits non-zero (e.g. when
+// xdg-open finds no handler) as well as when it cannot be launched (ENOENT).
+// The old exec() warned via the callback err; spawn uses 'close' + 'error'.
+function openBrowser(platform, url) {
+  const { spawn } = require('child_process')
+  const [cmd, args] = browserArgv(platform, url)
+  const proc = spawn(cmd, args)
+  proc.on('error', (err) => {
+    console.warn(`Não foi possível abrir o browser: ${err.message}`)
+  })
+  proc.on('close', (code) => {
+    if (code !== 0 && code !== null) {
+      console.warn(`Não foi possível abrir o browser: processo encerrou com código ${code}`)
+    }
+  })
+}
+
 // Mapa de extensão → Content-Type
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -67,7 +146,17 @@ const MIME = {
 
 /**
  * serveStatic serve arquivos do STATIC_DIR.
- * Retorna 404 se o arquivo não existe ou se o path tenta escape (path traversal).
+ *
+ * Modelo de segurança — contenção em dois estágios (M-03):
+ *
+ * 1. Contenção léxica: path.resolve() normaliza ".." e o resultado deve começar
+ *    com STATIC_DIR.  Caminhos fora recebem 403 antes de tocar o disco.
+ *
+ * 2. Contenção física: fs.realpathSync.native() é chamado no arquivo pedido e
+ *    comparado com REAL_STATIC_DIR (pré-computado no carregamento do módulo).
+ *    Um symlink dentro de STATIC_DIR cujo destino físico aponta para fora → 403.
+ *    Qualquer falha de canonicalização → 404.
+ *
  * @param {string} urlPath - pathname da URL (ex: '/static/app.js')
  * @param {http.ServerResponse} res
  */
@@ -76,25 +165,43 @@ function serveStatic(urlPath, res) {
   const relative = urlPath.replace(/^\/static/, '') || '/index.html'
   const resolved = path.resolve(path.join(STATIC_DIR, relative))
 
-  // Segurança: path traversal
-  if (!resolved.startsWith(path.resolve(STATIC_DIR) + path.sep) && resolved !== path.resolve(STATIC_DIR)) {
+  // ── Estágio 1: Contenção léxica ────────────────────────────────────────────
+  const lexicalStaticDir = path.resolve(STATIC_DIR)
+  if (!resolved.startsWith(lexicalStaticDir + path.sep) && resolved !== lexicalStaticDir) {
     res.writeHead(403, { 'Content-Type': 'text/plain' })
     res.end('Forbidden')
     return
   }
 
-  if (!fs.existsSync(resolved)) {
+  // ── Estágio 2: Contenção física ────────────────────────────────────────────
+  if (!REAL_STATIC_DIR) {
+    // STATIC_DIR não existe — nenhum arquivo pode ser servido.
+    res.writeHead(404, { 'Content-Type': 'text/plain' })
+    res.end('Not Found')
+    return
+  }
+
+  let realResolved
+  try {
+    realResolved = fs.realpathSync.native(resolved)
+  } catch (_) {
     res.writeHead(404, { 'Content-Type': 'text/plain' })
     res.end('Not Found')
     return
   }
 
-  const ext = path.extname(resolved).toLowerCase()
+  if (!realResolved.startsWith(REAL_STATIC_DIR + path.sep) && realResolved !== REAL_STATIC_DIR) {
+    res.writeHead(403, { 'Content-Type': 'text/plain' })
+    res.end('Forbidden')
+    return
+  }
+
+  const ext = path.extname(realResolved).toLowerCase()
   const contentType = MIME[ext] || 'application/octet-stream'
 
   let content
   try {
-    content = fs.readFileSync(resolved)
+    content = fs.readFileSync(realResolved)
   } catch (_) {
     res.writeHead(500, { 'Content-Type': 'text/plain' })
     res.end('Internal Server Error')
@@ -190,6 +297,14 @@ function createServeCommand() {
       const port = parseInt(opts.port, 10) || 8080
       const host = opts.host
 
+      // AC4 — validate --host before bind. Rejects metacharacter-bearing
+      // strings that would reach the browser-open path or the socket.
+      if (!isValidHost(host)) {
+        console.error(`trackfw serve: invalid --host value: ${host}`)
+        console.error('--host must be "localhost", a valid IPv4/IPv6 address, or an RFC-1123 hostname.')
+        process.exit(1)
+      }
+
       const server = createServer(cfg, port)
 
       if (!isLoopbackHost(host)) {
@@ -201,16 +316,8 @@ function createServeCommand() {
         console.log(`trackfw serve: ${url}`)
 
         if (opts.open !== false) {
-          // Tentar abrir o browser
-          const { exec } = require('child_process')
-          const platform = process.platform
-          let openCmd
-          if (platform === 'darwin') openCmd = `open "${url}"`
-          else if (platform === 'win32') openCmd = `start "" "${url}"`
-          else openCmd = `xdg-open "${url}"`
-          exec(openCmd, (err) => {
-            if (err) console.warn(`Não foi possível abrir o browser: ${err.message}`)
-          })
+          // AC1 — use argv (spawn), never shell string interpolation (exec).
+          openBrowser(process.platform, url)
         }
       })
 
@@ -235,4 +342,4 @@ function createServeCommand() {
   return cmd
 }
 
-module.exports = { createServeCommand, createServer, isLoopbackHost, displayUrl }
+module.exports = { createServeCommand, createServer, isLoopbackHost, displayUrl, isValidHost, browserArgv, openBrowser, serveStatic }

package/src/commands/update-harness.js

@@ -7,7 +7,7 @@ const identityStore = require('../identity')
 const projectConfig = require('../config')
 const { catalog, buildPlans, IntegrationManager, globalGroupPath } = require('../integrations')
 const { tildeify, validateTargets, buildDocument, humanReport, silenceConsole } = require('../lib/update-engine')
-const { mergeClaudeHookArray, mergeSimpleCommandArray, mergeCopilotHookArray, generateGlobalCredentialGuardScript, generateGlobalGitBranchGuardScript } = require('../generators/hooks')
+const { mergeClaudeHookArray, mergeSimpleCommandArray, mergeCopilotHookArray, GIT_BRANCH_GUARD_SCRIPT, GLOBAL_CREDENTIAL_GUARD_SCRIPT } = require('../generators/hooks')
 const { homedir } = require('../homedir')
 
 // `trackfw update harness` is the global counterpart to `trackfw update` —
@@ -73,6 +73,72 @@ Cadeia: **ADR → REQ → ROADMAP** · Estados: \`backlog / wip / blocked / done
 `
 }
 
+// gitBranchGuardScriptTarget — evaluates (and, unless --dry-run, applies) the
+// global git-branch-guard shell script at
+// ~/.trackfw/scripts/trackfw-git-branch-guard.sh.
+//
+// This target OWNS the script file. It compares content before writing so that
+// an already up-to-date script reports "skipped" and its mtime is left unchanged
+// (REQ-2026-09-09 AC3). Creation does not require --install-missing because
+// ~/.trackfw/scripts/ is 100% trackfw-owned.
+function gitBranchGuardScriptTarget(homeRoot, { dryRun }) {
+  const id = 'git-branch-guard-script'
+  const filePath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-git-branch-guard.sh')
+  const displayPath = tildeify(homeRoot, filePath)
+  const desired = GIT_BRANCH_GUARD_SCRIPT
+
+  try {
+    const exists = fs.existsSync(filePath)
+    const actual = exists ? fs.readFileSync(filePath, 'utf8') : null
+
+    if (exists && actual === desired) {
+      // Content identical — skip write, repair execute bit without touching mtime.
+      try { fs.chmodSync(filePath, 0o755) } catch (_) { /* best-effort */ }
+      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, { encoding: 'utf8', mode: 0o755 })
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+// credentialGuardScriptTarget — evaluates (and, unless --dry-run, applies) the
+// global credential-guard shell script at
+// ~/.trackfw/scripts/trackfw-credential-guard.sh.
+//
+// Mirrors gitBranchGuardScriptTarget — same ownership model, same idempotency
+// contract, same absence of --install-missing gate.
+function credentialGuardScriptTarget(homeRoot, { dryRun }) {
+  const id = 'credential-guard-script'
+  const filePath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-credential-guard.sh')
+  const displayPath = tildeify(homeRoot, filePath)
+  const desired = GLOBAL_CREDENTIAL_GUARD_SCRIPT
+
+  try {
+    const exists = fs.existsSync(filePath)
+    const actual = exists ? fs.readFileSync(filePath, 'utf8') : null
+
+    if (exists && actual === desired) {
+      // Content identical — skip write, repair execute bit without touching mtime.
+      try { fs.chmodSync(filePath, 0o755) } catch (_) { /* best-effort */ }
+      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, { encoding: 'utf8', mode: 0o755 })
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
 function claudeSkillTarget(homeRoot, { dryRun, installMissing }) {
   const id = 'claude-skill'
   const filePath = path.join(homeRoot, '.claude', 'skills', 'trackfw', 'SKILL.md')
@@ -799,7 +865,10 @@ function catalogBundleTarget(toolId, kind, homeRoot, identityConfig, { dryRun, i
 // which precede claude-agents/claude-skills), with credential-guard always
 // preceding git-branch-guard within a tool — see buildHarnessTargetIDs's
 // comment in update.go for the full rationale.
-const HARNESS_TARGET_IDS = ['claude-skill', 'claude-credential-guard', 'claude-git-branch-guard']
+// Script targets precede every wiring target that references them so that even
+// a --targets-filtered run that only requests a wiring target still finds the
+// script already in place from a prior full run.
+const HARNESS_TARGET_IDS = ['claude-skill', 'git-branch-guard-script', 'credential-guard-script', 'claude-credential-guard', 'claude-git-branch-guard']
 for (const target of catalog.targets) {
   if (target.id === 'codex') HARNESS_TARGET_IDS.push('codex-credential-guard', 'codex-git-branch-guard')
   if (target.id === 'gemini') HARNESS_TARGET_IDS.push('gemini-credential-guard', 'gemini-git-branch-guard')
@@ -818,6 +887,8 @@ 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('git-branch-guard-script')) targets.push(gitBranchGuardScriptTarget(homeRoot, { dryRun }))
+  if (include('credential-guard-script')) targets.push(credentialGuardScriptTarget(homeRoot, { dryRun }))
   if (include('claude-credential-guard')) targets.push(credentialGuardTargetClaude(homeRoot, { dryRun, installMissing }))
   if (include('claude-git-branch-guard')) targets.push(gitBranchGuardTargetClaude(homeRoot, { dryRun, installMissing }))
   for (const target of catalog.targets) {
@@ -885,20 +956,11 @@ function run(options) {
   const dryRun = Boolean(options.dryRun)
   const installMissing = Boolean(options.installMissing)
 
-  // The per-CLI *-credential-guard targets below only wire hook entries that
-  // point at ~/.trackfw/scripts/trackfw-credential-guard.sh — none of them
-  // write the script itself (ADR-2026-08-06, decision #2/#3). Without this
-  // call the wiring is installed but every hook invocation fails with
-  // "No such file or directory" because the script never exists.
-  if (!dryRun) {
-    if (options.json) {
-      silenceConsole(() => generateGlobalCredentialGuardScript(homeRoot))
-      silenceConsole(() => generateGlobalGitBranchGuardScript(homeRoot))
-    } else {
-      generateGlobalCredentialGuardScript(homeRoot)
-      generateGlobalGitBranchGuardScript(homeRoot)
-    }
-  }
+  // NOTE: the script files are now first-class targets ("git-branch-guard-script",
+  // "credential-guard-script") positioned before the wiring targets in
+  // HARNESS_TARGET_IDS. The pre-loop unconditional writes that used to live here
+  // have been removed — the target functions handle creation and idempotency.
+  // (REQ-2026-09-09, ML-1A)
 
   // Identidade resolvida do disco antes de buildPlans — pular esta etapa
   // reverteria silenciosamente os nomes customizados para os defaults

package/src/config/index.js

@@ -356,6 +356,26 @@ function readAgentConventions(cwd) {
   return cfg.update.agentConventions || '';
 }
 
+// readNamespacingConfig reads roadmap_namespacing and agents from <cwd>/trackfw.yaml, bypassing
+// the load() singleton — mirrors Go's config.ReadNamespacingConfig. Never throws; returns
+// defaults ('flat', []) on any failure.
+function readNamespacingConfig(cwd) {
+  let content;
+  try {
+    content = fs.readFileSync(path.join(cwd || process.cwd(), 'trackfw.yaml'), 'utf8');
+  } catch (_) {
+    return { namespacing: 'flat', agents: [] };
+  }
+  const cfg = { rules: {}, credentialGuard: {}, update: {}, sync: {}, linkFields: {}, agentModels: {},
+    roadmapNamespacing: 'flat', agents: [] };
+  try {
+    parse(content, cfg);
+  } catch (_) {
+    return { namespacing: 'flat', agents: [] };
+  }
+  return { namespacing: cfg.roadmapNamespacing || 'flat', agents: cfg.agents || [] };
+}
+
 // _cwdAgentModelsSource returns 'project_only' if cwd's trackfw.yaml has agent_models configured,
 // 'none' otherwise. Used for the AC14 diagnostic in loadGlobalAgentModels.
 function _cwdAgentModelsSource(cwd) {
@@ -425,6 +445,7 @@ module.exports = {
   expandPath,
   parseRulesFromContent,
   readAgentConventions,
+  readNamespacingConfig,
   loadGlobalAgentModels,
   resolveAgentModels,
   NAMESPACING_FLAT,

package/src/generators/hooks.js

@@ -2409,5 +2409,6 @@ module.exports = {
   SIGNAL_SCRIPT,
   CLEANUP_SCRIPT,
   CREDENTIAL_GUARD_SCRIPT,
+  GLOBAL_CREDENTIAL_GUARD_SCRIPT,
   GIT_BRANCH_GUARD_SCRIPT,
 }