trackfw 7.5.0 → 7.6.0

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'")