trackfw 7.5.1 → 7.6.0

package/package.json

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

@@ -3,7 +3,7 @@
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
-const { readAgentConventions } = require('../config/index.js')
+const { readAgentConventions, readNamespacingConfig, NAMESPACING_BY_AGENT } = require('../config/index.js')
 const { homedir } = require('../homedir');
 
 // PACKAGE_VERSION — the version of the trackfw binary generating the CI
@@ -499,7 +499,7 @@ const AGENT_HEADERS = {
   cursor:   '---\ndescription: trackfw governance rules\nglob: "**/*"\nalwaysApply: true\n---\n',
 }
 
-function trackfwRulesBlock(agentConventions) {
+function trackfwRulesBlock(agentConventions, namespacing, agents) {
   let conventionsSection = ''
   if (agentConventions && String(agentConventions).trim() !== '') {
     conventionsSection = `
@@ -513,6 +513,19 @@ ${String(agentConventions).trim()}
 `
   }
 
+  // Determine step-1 command form — by_agent + 2+ agents shows --agent variant
+  const nonEmpty = (agents || []).filter(a => a)
+  const isMulti = namespacing === NAMESPACING_BY_AGENT && nonEmpty.length >= 2
+  const step1Req = isMulti
+    ? `\`trackfw req new --agent <agent> "title"\``
+    : `\`trackfw req new "title"\``
+  const step1Roadmap = isMulti
+    ? `\`trackfw roadmap new --agent <agent> "title"\``
+    : `\`trackfw roadmap new "title"\``
+  const step1Note = isMulti
+    ? `\n   ⚠️ \`--agent\` is required for this project (agents: ${nonEmpty.join(', ')})`
+    : ''
+
   return RULES_START + `
 ## trackfw — Governance Rules
 
@@ -521,7 +534,7 @@ Chain: \`ADR → REQ → ROADMAP\` · States: \`backlog / analyzing / wip / bloc
 
 ### Agent Protocol
 1. **Before any implementation (mandatory):** create governance artifacts FIRST, then branch:
-   \`trackfw req new "title"\` → \`trackfw roadmap new "title"\` → \`trackfw roadmap move <name> wip\` → \`git checkout -b feat/<branch>\`
+   ${step1Req} → ${step1Roadmap} → \`trackfw roadmap move <name> wip\` → \`git checkout -b feat/<branch>\`${step1Note}
    ❌ Never create a branch before REQ + ROADMAP are in wip/
    ❌ Never defer REQ/ROADMAP creation to a future task — they are prerequisites, not deliverables
    ✓ \`trackfw validate\` enforces this via \`branch_has_wip_roadmap\` rule (v2.7.0+)
@@ -574,7 +587,8 @@ Delete the file when resolved. Visible as a live banner in \`trackfw serve\`.
 function injectOrUpdateRules(filePath, headerIfNew, cwd) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true })
 
-  const block = trackfwRulesBlock(readAgentConventions(cwd))
+  const { namespacing, agents: nsAgents } = readNamespacingConfig(cwd)
+  const block = trackfwRulesBlock(readAgentConventions(cwd), namespacing, nsAgents)
 
   if (!fs.existsSync(filePath)) {
     let content = headerIfNew || ''
@@ -688,8 +702,17 @@ function generateClaudeMD(cfg) {
   content += '| Command | When to use |\n'
   content += '|---|---|\n'
   content += '| `trackfw adr new "title"` | Create ADR |\n'
-  content += '| `trackfw req new "title"` | Create REQ |\n'
-  content += '| `trackfw roadmap new` | Create empty roadmap linked to a REQ |\n'
+  {
+    const nsNonEmpty = (cfg.agents || []).filter(a => a)
+    if (cfg.roadmapNamespacing === NAMESPACING_BY_AGENT && nsNonEmpty.length >= 2) {
+      const agentList = nsNonEmpty.join(', ')
+      content += `| \`trackfw req new --agent <agent> "title"\` | Create REQ (\`--agent\` required; agents: ${agentList}) |\n`
+      content += '| `trackfw roadmap new --agent <agent>` | Create roadmap linked to a REQ (`--agent` required) |\n'
+    } else {
+      content += '| `trackfw req new "title"` | Create REQ |\n'
+      content += '| `trackfw roadmap new` | Create empty roadmap linked to a REQ |\n'
+    }
+  }
   content += '| `trackfw roadmap move <name> <state>` | Move roadmap state |\n'
   content += '| `trackfw validate` | Governance validation gate |\n'
   content += '| `trackfw status` | Show governance status |\n\n'
@@ -898,6 +921,8 @@ trackfw não está instalado. Instale com uma das opções:
 
     'req.md': `Execute o seguinte comando bash: \`trackfw req new "$ARGUMENTS"\`
 
+⚠️ Em projetos com \`roadmap_namespacing: by_agent\` e 2+ agentes, use: \`trackfw req new --agent <seu-agente> "$ARGUMENTS"\`
+
 Se o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:
 
 \`\`\`

package/src/generators/req.js

@@ -242,13 +242,22 @@ function toSlug(s) {
 /**
  * newREQ — cria docs/req/REQ-YYYY-MM-DD-<slug>.md.
  * @param {{ title: string, motivation?: string, criteria?: string, dependsOnADRs?: string[] }} content
+ * @param {string} [agent] - agente explícito via --agent (AC4/AC5/AC10)
  * @returns {Promise<void>}
  */
-async function newREQ(content) {
+async function newREQ(content, agent) {
   // Ponto único de decisão de caminho de ESCRITA (ADR-2026-09-03, D2/D4): by_agent grava no
   // canônico req_dir/<agente>/; flat grava em req_dir/ — o mesmo ponto que alimenta a união de leitura.
+  // Em by_agent com múltiplos namespaces sem --agent, reqWriteDir lança erro de ambiguidade (AC5/AC10).
   const cfg = require('../config').load()
-  const reqDir = reqWriteDir(cfg) || cfg.reqDir
+  let reqDir
+  try {
+    reqDir = reqWriteDir(cfg, agent) || cfg.reqDir
+  } catch (err) {
+    console.error(`Error: ${err.message}`)
+    process.exitCode = 1
+    return
+  }
   fs.mkdirSync(reqDir, { recursive: true })
 
   const slug = toSlug(content.title)

package/src/generators/roadmap.js

@@ -3,7 +3,7 @@ const fs = require('fs')
 const path = require('path')
 const config = require('../config')
 const { localDateISO } = require('./date')
-const { resolveReqFiles, resolveAgentNamespaces } = require('../validator/index.js')
+const { resolveReqFiles, resolveAgentNamespaces, resolveAgentForWrite, roadmapNewLine } = require('../validator/index.js')
 const { normalizeRefSeparator: pathfmtNormalizeRefSeparator } = require('../lib/pathfmt')
 const { normalizeCRLF } = require('../integrations/render')
 
@@ -65,13 +65,43 @@ function stateDir(state) {
   return cfg.roadmapDir + '/' + state
 }
 
+// agentFromPath — extrai o nome do agente a partir de um caminho de arquivo dentro de baseDir.
+// Estratégia relative-to-base: relativiza o filePath em relação a baseDir e retorna o primeiro
+// segmento do caminho relativo. Funciona para:
+//   req_dir/<agent>/REQ-x.md          → agent
+//   req_dir/<agent>/wip/REQ-x.md      → agent  (layout legado)
+//   roadmap_dir/<agent>/wip/R.md      → agent
+// Usa realpathSync para resolver symlinks antes de computar o relativo — necessário no macOS onde
+// /var é link para /private/var: sem resolução, path.relative produz '../..' em vez do agente.
+// Equivalente ao agentDir/agent inline do moveRoadmap — extraído para função nomeada (AC11).
+function agentFromPath(filePath, baseDir) {
+  let abs, base
+  try {
+    abs = fs.realpathSync(filePath)
+  } catch (_) {
+    abs = path.resolve(filePath)
+  }
+  try {
+    base = fs.realpathSync(path.resolve(baseDir))
+  } catch (_) {
+    base = path.resolve(baseDir)
+  }
+  const rel = path.relative(base, abs)
+  const parts = rel.split(path.sep)
+  // Arquivo direto em baseDir (1 segmento): não é um namespace, retorna vazio.
+  // Segmento inválido ('.' ou '..'): baseDir não contém filePath, retorna vazio.
+  if (parts.length < 2) return ''
+  if (!parts[0] || parts[0] === '.' || parts[0] === '..') return ''
+  return parts[0]
+}
+
 // agentStateDir retorna o diretório para um agente+estado em modo by_agent.
-// agent=null usa o primeiro agente configurado (ou "default" se lista vazia).
+// agent=null: delega a resolveAgentForWrite (que lança em multi-agente sem flag — AC5).
 function agentStateDir(agent, state) {
   const cfg = config.load()
   if (!VALID_STATES.includes(state)) return null
   if (!agent) {
-    agent = cfg.agents && cfg.agents.length > 0 ? cfg.agents[0] : 'default'
+    agent = resolveAgentForWrite(cfg, undefined)
   }
   return cfg.roadmapDir + '/' + agent + '/' + state
 }
@@ -123,7 +153,7 @@ function listRoadmaps() {
   }
 
   if (!found) {
-    console.log("Nenhum roadmap encontrado. Crie um com 'trackfw roadmap new'.")
+    console.log(`Nenhum roadmap encontrado. Crie um com '${roadmapNewLine(cfg)}'.`)
   }
 }
 
@@ -264,8 +294,12 @@ function moveRoadmap(name, state) {
   let targetDir, fromState, logBasename
 
   if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
-    const agentDir = path.dirname(path.dirname(src))
-    const agent = path.basename(agentDir)
+    const agent = agentFromPath(src, cfg.roadmapDir)
+    if (!agent) {
+      console.error(`cannot determine agent namespace for "${src}" — path is outside roadmap directory or resolves via symlink to an external location`)
+      process.exitCode = 1
+      return
+    }
     fromState = path.basename(path.dirname(src))
     targetDir = agentStateDir(agent, state)
     if (!targetDir) {
@@ -492,9 +526,12 @@ function syncReqReferences(movedBasename, newRoadmapPath, cfg) {
 
 /**
  * newRoadmap — cria roadmap em <roadmapDir>/backlog/ROADMAP-YYYY-MM-DD-<slug>.md.
- * Em modo by_agent, usa o primeiro agente configurado.
+ * Em modo by_agent, usa o agente explícito ou detecta via resolveAgentForWrite (AC4/AC5).
+ * @param {string} title
+ * @param {string} reqPath - caminho da REQ vinculada (opcional)
+ * @param {string} [agent] - agente explícito via --agent (opcional; derivado da REQ se --req fornecido)
  */
-function newRoadmap(title, reqPath) {
+function newRoadmap(title, reqPath, agent) {
   // AC1/AC2: o título é dado de uma linha — newline e CR são entrada malformada.
   // Mensagem byte-idêntica nos 3 CLIs (docs/cli-parity.md).
   if (/[\n\r]/.test(title)) {
@@ -508,8 +545,20 @@ function newRoadmap(title, reqPath) {
   const slug = toSlug(title)
 
   let backlogDir
+  let resolvedAgent = ''
   if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
-    backlogDir = agentStateDir(null, 'backlog')
+    // AC11: se --req fornecido e sem --agent explícito, deriva o agente da REQ (reusa agentFromPath)
+    if (!agent && reqPath) {
+      agent = agentFromPath(reqPath, cfg.reqDir || 'docs/req')
+    }
+    try {
+      resolvedAgent = resolveAgentForWrite(cfg, agent)
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exitCode = 1
+      return
+    }
+    backlogDir = agentStateDir(resolvedAgent, 'backlog')
     if (!backlogDir) {
       console.error('cannot resolve backlog dir in by_agent mode')
       process.exitCode = 1
@@ -523,12 +572,13 @@ function newRoadmap(title, reqPath) {
   fs.mkdirSync(backlogDir, { recursive: true })
 
   const reqField = reqPath ? `"${reqPath}"` : '""'
+  const squadField = resolvedAgent ? `"${resolvedAgent}"` : '""'
 
   const body = `---
 status: backlog
 date: ${date}
 req: ${reqField}
-squad: ""
+squad: ${squadField}
 ---
 
 # Roadmap: ${title}
@@ -564,8 +614,10 @@ ${WAVE0_BLOCK}## Wave 1 — <name> (parallel MLs)
 /**
  * newRoadmapFromReq — lê uma REQ e gera roadmap pré-preenchido com MLs extraídos
  * dos critérios de aceite.
+ * @param {string} reqPath
+ * @param {string} [agent] - agente explícito via --agent (AC11: herda do path da REQ se omitido)
  */
-function newRoadmapFromReq(reqPath) {
+function newRoadmapFromReq(reqPath, agent) {
   let data
   try {
     data = fs.readFileSync(reqPath, 'utf8')
@@ -591,8 +643,20 @@ function newRoadmapFromReq(reqPath) {
   const slug = toSlug(title)
 
   let backlogDir
+  let resolvedAgent = ''
   if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
-    backlogDir = agentStateDir(null, 'backlog')
+    // AC11: herda o agente do caminho da REQ reusando agentFromPath (mesmo mecanismo de moveRoadmap)
+    if (!agent) {
+      agent = agentFromPath(reqPath, cfg.reqDir || 'docs/req')
+    }
+    try {
+      resolvedAgent = resolveAgentForWrite(cfg, agent)
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exitCode = 1
+      return
+    }
+    backlogDir = agentStateDir(resolvedAgent, 'backlog')
     if (!backlogDir) {
       console.error('cannot resolve backlog dir in by_agent mode')
       process.exitCode = 1
@@ -622,12 +686,13 @@ function newRoadmapFromReq(reqPath) {
   const mlSection = WAVE0_BLOCK + mlLines.join('\n')
 
   const adrRef = linkedADR ? `\nADR: ${linkedADR}` : ''
+  const squadField = resolvedAgent ? `"${resolvedAgent}"` : '""'
 
   const body = `---
 status: backlog
 date: ${date}
 req: "${reqPath}"
-squad: ""
+squad: ${squadField}
 ---
 
 # Roadmap: ${title}
@@ -769,6 +834,7 @@ module.exports = {
   newRoadmapFromReq,
   stateDir,
   agentStateDir,
+  agentFromPath,
   VALID_STATES,
   STATE_ORDER,
   toSlug,

package/src/integrations/index.js

@@ -9,6 +9,7 @@ const { legacyHashes } = require('./legacy')
 const identityStore = require('../identity')
 const { injectRulesForTool } = require('../generators/init')
 const { applyThirdPartyReferences } = require('../thirdparty/references')
+const { registerAgentInConfig } = require('./register-agent')
 const { homedir } = require('../homedir')
 
 function parseSurfaces(values = []) {
@@ -141,6 +142,27 @@ function execute(kind, operation, options = {}, roots = {}) {
   if (operation === 'install') {
     const targetValues = options.targets && options.targets.length ? options.targets : catalog.targets.map(entry => entry.id)
     for (const targetID of targetValues) injectRulesForTool(targetID, manager.roots.project)
+
+    // ML-2B: register installed catalog agent IDs in trackfw.yaml `agents:` so
+    // that `trackfw req new` / `roadmap new` can route to the agent namespace.
+    // Guard: only for `agents` kind (not skills), project scope (global installs
+    // do not own the project's trackfw.yaml), and only when install operation
+    // succeeds (same call site as injectRulesForTool above).
+    // Name written: plan.claim.item (the catalog ID, e.g. "architect") — chosen
+    // over the artifact file name ("trackfw-architect") to stay consistent with
+    // the namespace format already used in trackfw.yaml's agents: list (bare
+    // names, no prefix). Surfaced in handback for parity binding across Go/Python.
+    if (kind === 'agents') {
+      const projectRoot = options.projectRoot || manager.roots.project
+      const installedItems = [...new Set(
+        plans
+          .filter(p => p.claim.scope === 'project')
+          .map(p => p.claim.item)
+      )]
+      for (const agentName of installedItems) {
+        registerAgentInConfig(projectRoot, agentName)
+      }
+    }
   }
 
   return result(kind, plans, statuses)

package/src/integrations/register-agent.js

@@ -0,0 +1,106 @@
+'use strict'
+
+// registerAgentInConfig — ML-2B (Node)
+//
+// When `trackfw agents install` runs inside a project configured with
+// `roadmap_namespacing: by_agent`, the installed catalog item ID (e.g.
+// "architect") is registered as a namespace entry in the `agents:` list of
+// `trackfw.yaml`, enabling `trackfw req new` / `roadmap new` to route
+// artefacts to that agent's subdirectory.
+//
+// Scope gate: only project-scoped installs write the key. Global installs
+// (scope === "global") install files into the user's home directory and do
+// NOT own any project's trackfw.yaml — we must not write it.
+//
+// Format preservation: we use yaml.parseDocument / doc.toString() which is
+// the documented round-trip that preserves comments, key order and blank
+// lines. We do NOT re-serialise the whole document through yaml.dump so that
+// a diff of trackfw.yaml only shows the added line(s) in the agents: block
+// (AC3). See the AC3 test for the exact assertion.
+//
+// Idempotency: if the agent name is already in the list we return early
+// without touching the file (AC1).
+//
+// flat mode: if roadmap_namespacing is not "by_agent" we do nothing at all —
+// the agents: key MUST NOT be created (AC2).
+//
+// Inline-flow guard: if agents: is written in inline/flow style (e.g.
+// `agents: [alpha, beta]`) we do NOT rewrite the file. Rewriting would change
+// the user's formatting without their consent. Instead we emit a warning to
+// stderr naming the file path and the item, and return — the persona install
+// itself succeeds. Mirrors Go behaviour (the reference runtime).
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { parseDocument } = require('yaml')
+
+const CONFIG_FILE = 'trackfw.yaml'
+
+/**
+ * Return true if the raw YAML text has an `agents:` key written in inline/flow
+ * style on the same line (e.g. `agents: [alpha, beta]`), ignoring comment lines.
+ *
+ * We test on the raw text before parsing so that we never mutate a document
+ * whose style we cannot faithfully reproduce.
+ */
+function isAgentsInlineFlow(raw) {
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trimStart()
+    if (trimmed.startsWith('#')) continue
+    // Non-comment line that starts the `agents:` mapping key and has `[` on it
+    if (/^agents\s*:.*\[/.test(trimmed)) return true
+  }
+  return false
+}
+
+/**
+ * Register `agentName` in the `agents:` list of `<projectRoot>/trackfw.yaml`.
+ *
+ * No-op when:
+ *  - trackfw.yaml does not exist in projectRoot (nothing to update)
+ *  - roadmap_namespacing is absent or not "by_agent"         (AC2)
+ *  - agentName is already present in the list                (AC1 idempotency)
+ *  - agents: is in inline/flow format — warns to stderr, skips write
+ *
+ * @param {string} projectRoot  Absolute path to the project directory.
+ * @param {string} agentName    Catalog item ID (e.g. "architect").
+ */
+function registerAgentInConfig(projectRoot, agentName) {
+  const cfgPath = path.join(projectRoot, CONFIG_FILE)
+  if (!fs.existsSync(cfgPath)) return
+
+  const raw = fs.readFileSync(cfgPath, 'utf8')
+  const doc = parseDocument(raw)
+
+  // AC2 gate: only act when roadmap_namespacing is exactly "by_agent"
+  const namespacing = doc.get('roadmap_namespacing')
+  if (namespacing !== 'by_agent') return
+
+  // Inline-flow guard: refuse to rewrite a file the user authored in flow style.
+  // Mirrors Go: "warning: could not register agent ... trackfw.yaml has agents:
+  // in inline-flow format; edit <path> manually to add <item>"
+  if (isAgentsInlineFlow(raw)) {
+    process.stderr.write(
+      `warning: could not register agent "${agentName}" in trackfw.yaml:\n` +
+      `trackfw.yaml has agents: in inline-flow format; edit ${cfgPath} manually to add "${agentName}"\n`
+    )
+    return
+  }
+
+  // Collect current agents list (may be absent)
+  const agentsNode = doc.getIn(['agents'], true)
+
+  if (agentsNode) {
+    // List present — check for idempotency (AC1)
+    const existing = agentsNode.items.map(item => item.value)
+    if (existing.includes(agentName)) return
+    agentsNode.items.push(doc.createNode(agentName))
+  } else {
+    // List absent — create it (AC2 already passed: namespacing === 'by_agent')
+    doc.set('agents', doc.createNode([agentName]))
+  }
+
+  fs.writeFileSync(cfgPath, doc.toString(), 'utf8')
+}
+
+module.exports = { registerAgentInConfig }

package/src/push/runner.js

@@ -30,6 +30,8 @@ function defaultCheckGovernance() {
   return checkShipGovernance()
 }
 
+const { load: loadConfig } = require('../config')
+const validator = require('../validator')
 const { resolve: forgeResolve } = require('../forge/resolve')
 const { forgeAdapter } = require('../forge/adapter')
 
@@ -127,8 +129,9 @@ function runPush(opts, deps) {
         writeln(`  ${v}`)
       }
       writeln('\nCreate the required artifacts before running push:')
-      writeln('  trackfw req new "<title>"')
-      writeln('  trackfw roadmap new "<title>"')
+      const pushCfg = loadConfig()
+      writeln(`  ${validator.reqNewLine(pushCfg)}`)
+      writeln(`  ${validator.roadmapNewLine(pushCfg)}`)
       writeln('  trackfw roadmap move <name> wip')
       writeln("\nNote: this governance check is a hard gate — it is not affected by lenient")
       writeln("mode or per-rule severity configured in trackfw.yaml. If 'trackfw validate'")

package/src/serve/api_file.js

@@ -4,15 +4,15 @@ const fs = require('fs')
 const path = require('path')
 
 /**
- * isPathAllowed verifica se o filePath resolvido está dentro de um dos diretórios permitidos.
- * @param {string} resolved - path.resolve(filePath)
- * @param {string[]} allowedDirs - lista de diretórios permitidos (já resolvidos)
+ * isPathAllowed verifica se absPath está dentro de um dos diretórios permitidos.
+ * Usa separador no sufixo para evitar que /docs/adr case com /docs/adr2.
+ * @param {string} absPath
+ * @param {string[]} allowedDirs
  * @returns {boolean}
  */
-function isPathAllowed(resolved, allowedDirs) {
+function isPathAllowed(absPath, allowedDirs) {
   for (const dir of allowedDirs) {
-    // garantir que o path começa com dir + separador
-    if (resolved === dir || resolved.startsWith(dir + path.sep)) {
+    if (absPath === dir || absPath.startsWith(dir + path.sep)) {
       return true
     }
   }
@@ -21,7 +21,22 @@ function isPathAllowed(resolved, allowedDirs) {
 
 /**
  * handleFile responde ao GET /api/file?path=... com o conteúdo do arquivo.
- * Retorna 400 se path ausente, 403 se fora dos diretórios permitidos, 404 se não existe.
+ *
+ * Modelo de segurança — contenção em dois estágios:
+ *
+ * 1. Contenção léxica (sem acesso ao filesystem): path.resolve() normaliza ".."
+ *    e o resultado deve começar com uma das raízes autorizadas.  Caminhos fora
+ *    das raízes recebem 403 antes de qualquer acesso ao disco, impedindo que a
+ *    distinção 403 vs 404 sirva de oracle de existência para caminhos arbitrários.
+ *
+ * 2. Contenção física (resolução de symlinks): fs.realpathSync.native() é chamado
+ *    no arquivo pedido e em cada raiz autorizada.  Um symlink cujo nome está
+ *    dentro de uma raiz autorizada mas cujo destino físico não está → 403.
+ *    Qualquer falha de canonicalização (ENOENT, symlink pendente, …) → 404.
+ *
+ * Um symlink legítimo cujo destino também está dentro de uma raiz autorizada
+ * continua sendo servido normalmente.
+ *
  * @param {object} cfg
  * @param {http.IncomingMessage} req
  * @param {http.ServerResponse} res
@@ -43,10 +58,10 @@ function handleFile(cfg, req, res) {
     return
   }
 
-  // Resolver o path absoluto para verificar segurança
+  // ── Estágio 1: Contenção léxica ────────────────────────────────────────────
+  // path.resolve() resolve '..' mas NÃO segue symlinks (operação puramente léxica).
   const resolved = path.resolve(filePath)
 
-  // Montar lista de diretórios permitidos a partir da config
   const adrDirs = (cfg.adrDirs || ['docs/adr']).map(d => path.resolve(d))
   const reqDir = path.resolve(cfg.reqDir || 'docs/req')
   const roadmapDir = path.resolve(cfg.roadmapDir || 'docs/roadmaps')
@@ -58,15 +73,37 @@ function handleFile(cfg, req, res) {
     return
   }
 
-  if (!fs.existsSync(resolved)) {
+  // ── Estágio 2: Contenção física ────────────────────────────────────────────
+  // Canonicalizar o arquivo pedido. Qualquer erro (ENOENT, symlink pendente,
+  // loop, permissão) → 404. O arquivo está nominalmente dentro de uma raiz
+  // autorizada (estágio 1 passou), portanto 404 é o resultado correto quando
+  // ele simplesmente não existe.
+  let realResolved
+  try {
+    realResolved = fs.realpathSync.native(resolved)
+  } catch (_) {
     res.writeHead(404, { 'Content-Type': 'text/plain' })
     res.end('Not Found')
     return
   }
 
+  // Canonicalizar as raízes autorizadas. Raízes inexistentes são ignoradas —
+  // nenhum arquivo pode residir em um diretório que não existe.
+  const realAllowedDirs = allowedDirs.flatMap(d => {
+    try { return [fs.realpathSync.native(d)] } catch (_) { return [] }
+  })
+
+  // Contenção física: o destino canônico deve estar dentro de uma raiz canônica.
+  if (!isPathAllowed(realResolved, realAllowedDirs)) {
+    res.writeHead(403, { 'Content-Type': 'text/plain' })
+    res.end('Forbidden')
+    return
+  }
+
+  // O arquivo existe (realpathSync não falhou) — ler da rota canônica.
   let content
   try {
-    content = fs.readFileSync(resolved, 'utf8')
+    content = fs.readFileSync(realResolved, 'utf8')
   } catch (err) {
     res.writeHead(500, { 'Content-Type': 'text/plain' })
     res.end('Internal Server Error')

package/src/ship/runner.js

@@ -499,8 +499,9 @@ function runShip(opts, deps = {}) {
         writeln(`  ${v}`)
       }
       writeln('\nCreate the required artifacts before running ship:')
-      writeln('  trackfw req new "<title>"')
-      writeln('  trackfw roadmap new "<title>"')
+      const shipCfg = loadConfig()
+      writeln(`  ${validator.reqNewLine(shipCfg)}`)
+      writeln(`  ${validator.roadmapNewLine(shipCfg)}`)
       writeln('  trackfw roadmap move <name> wip')
       writeln("\nNote: this governance check is a hard gate — it is not affected by lenient")
       writeln("mode or per-rule severity configured in trackfw.yaml. If 'trackfw validate'")

package/src/validator/index.js

@@ -414,18 +414,33 @@ function listReqMdFiles(dir) {
   } catch (_) { return [] }
 }
 
+// resolveAgentForWrite — ponto único de resolução do agente de escrita em modo by_agent.
+// Regra (AC5, AC10, KG 2026-08-29):
+//   - explicitAgent fornecido  → usa-o (AC4/AC5b: valor fora de agents: é permitido, produz violação de namespace)
+//   - agents: com UM namespace → usa aquele, sem erro (AC14: projeto single-agent nunca vê o erro)
+//   - agents: vazio            → usa "default"
+//   - agents: com VÁRIOS       → lança erro nomeando todas as opções (AC5: silêncio de agents[0] deixa de existir)
+// Nomes vazios em agents: não contam (agents: ["", "zeus"] é UM namespace) — filter antes de contar.
+function resolveAgentForWrite(cfg, explicitAgent) {
+  if (explicitAgent) return explicitAgent
+  const agents = (cfg.agents || []).filter(a => a)
+  if (agents.length === 0) return 'default'
+  if (agents.length === 1) return agents[0]
+  throw new Error(`by_agent project has multiple agent namespaces (${agents.join(', ')}): use --agent to specify one`)
+}
+
 // reqWriteDir é o PONTO ÚNICO que decide ONDE uma REQ nova é gravada (ADR-2026-09-03, D2/D4):
 //   flat     → req_dir/
-//   by_agent → req_dir/<agente>/   (primeiro de agents:, ou "default" se a lista é vazia)
+//   by_agent → req_dir/<agente>/   (agente resolvido via resolveAgentForWrite — AC4/AC5/AC10)
 // Consumido pelo gerador (newREQ); a união de leitura abaixo contém este diretório por construção.
-function reqWriteDir(cfg) {
+// Lança Error em by_agent com múltiplos namespaces e sem agente explícito (AC5).
+function reqWriteDir(cfg, agent) {
   const reqDir = cfg.reqDir || cfg.req_dir || ''
   if (!reqDir) return ''
   const namespacing = cfg.roadmapNamespacing || cfg.roadmap_namespacing || ''
   if (namespacing === 'by_agent') {
-    const agents = (cfg.agents || []).filter(a => a)
-    const agent = agents.length > 0 ? agents[0] : 'default'
-    return path.join(reqDir, agent)
+    const resolvedAgent = resolveAgentForWrite(cfg, agent)
+    return path.join(reqDir, resolvedAgent)
   }
   return reqDir
 }
@@ -1500,12 +1515,37 @@ function branchSlugMatchesRoadmap(branchSlug, wipDirs, doneDirs) {
   return { matched, candidates }
 }
 
+// isMultiAgentByAgent returns {multi: bool, agents: string[]} — parity with Go's IsMultiAgentByAgent.
+// multi is true only when roadmap_namespacing is "by_agent" AND there are 2+ non-empty agent names.
+function isMultiAgentByAgent(cfg) {
+  const ns = cfg.roadmapNamespacing || cfg.roadmap_namespacing || ''
+  if (ns !== 'by_agent') return { multi: false, agents: [] }
+  const nonEmpty = (cfg.agents || []).filter(a => a)
+  if (nonEmpty.length < 2) return { multi: false, agents: nonEmpty }
+  return { multi: true, agents: nonEmpty }
+}
+
+// reqNewLine returns the correct `trackfw req new` command for the project — parity with Go's ReqNewLine.
+function reqNewLine(cfg) {
+  const { multi, agents } = isMultiAgentByAgent(cfg)
+  if (multi) return `trackfw req new --agent <agent> "title"  # agents: ${agents.join(', ')}`
+  return 'trackfw req new "title"'
+}
+
+// roadmapNewLine returns the correct `trackfw roadmap new` command — parity with Go's RoadmapNewLine.
+function roadmapNewLine(cfg) {
+  const { multi } = isMultiAgentByAgent(cfg)
+  if (multi) return 'trackfw roadmap new --agent <agent> "title"'
+  return 'trackfw roadmap new "title"'
+}
+
 // branchGovernanceOrientation is the guidance message printed when a feat/fix/refactor branch has
 // no roadmap in wip/ nor done/ at all (candidates is empty). Shared by validateBranchHasWIPRoadmap
 // and `trackfw branch new` — never duplicate this string. Byte-identical to Go's
 // BranchGovernanceOrientation.
-function branchGovernanceOrientation(branch) {
-  return `branch "${branch}" is a feat/fix/refactor branch but no roadmap is in wip/ nor done/ — create governance artifacts first:\n  trackfw req new "title"\n  trackfw roadmap new "title"\n  trackfw roadmap move <name> wip`
+function branchGovernanceOrientation(branch, cfg) {
+  const cfgObj = cfg || {}
+  return `branch "${branch}" is a feat/fix/refactor branch but no roadmap is in wip/ nor done/ — create governance artifacts first:\n  ${reqNewLine(cfgObj)}\n  ${roadmapNewLine(cfgObj)}\n  trackfw roadmap move <name> wip`
 }
 
 // branchNoMatchingRoadmapMessage is the guidance message printed when roadmaps exist in wip/ or
@@ -1548,7 +1588,7 @@ function validateBranchHasWIPRoadmap() {
   if (matched) return []
 
   if (candidates.length === 0) {
-    return [branchGovernanceOrientation(branch)]
+    return [branchGovernanceOrientation(branch, cfg)]
   }
   return [branchNoMatchingRoadmapMessage(branch, candidates)]
 }
@@ -3962,6 +4002,7 @@ module.exports = {
   tryListDir,
   resolveReqFiles,
   reqWriteDir,
+  resolveAgentForWrite,
   resolveStateDirs,
   resolveWIPDirs,
   resolveDoneDirs,
@@ -3980,6 +4021,9 @@ module.exports = {
   validateBranchHasWIPRoadmap,
   // novas funções — trackfw branch new (extraídas do gate branch_has_wip_roadmap)
   branchSlugMatchesRoadmap,
+  isMultiAgentByAgent,
+  reqNewLine,
+  roadmapNewLine,
   branchGovernanceOrientation,
   branchNoMatchingRoadmapMessage,
   normalizeBranchSlug,