trackfw 6.3.1 → 6.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "trackfw",
-  "version": "6.3.1",
-  "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, and Amazon Q.",
+  "version": "6.4.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",
     "adr",

package/src/branch/runner.js

@@ -0,0 +1,140 @@
+'use strict'
+
+/**
+ * branch/runner.js — Core implementation of `trackfw branch new`.
+ *
+ * Moves the branch_has_wip_roadmap governance gate (already enforced by `trackfw validate` and
+ * `trackfw ship`) to before branch creation, instead of after. Mirrors internal/commands/branch.go
+ * byte-for-byte in behavior and message text — Go is the behavioral reference
+ * (docs/cli-parity.md: "Go is the behavioral reference").
+ *
+ * All git write operations are injectable for testability — never runs a real `git checkout -b`
+ * in unit tests.
+ */
+
+const { spawnSync } = require('child_process')
+const config = require('../config')
+const validator = require('../validator')
+
+// branchValidTypes mirrors the vocabulary already enforced by `trackfw ship` (feat|fix|refactor).
+const branchValidTypes = new Set(['feat', 'fix', 'refactor'])
+
+/**
+ * parseBranchSpec splits "<type>/<slug>" and validates both parts. type must be one of
+ * feat, fix, refactor (branchValidTypes); slug must be non-empty.
+ * @param {string} spec
+ * @returns {{ branchType: string, slug: string }}
+ * @throws {Error} when spec is malformed
+ */
+function parseBranchSpec(spec) {
+  const value = String(spec)
+  const idx = value.indexOf('/')
+  if (idx === -1 || value.slice(0, idx) === '') {
+    throw new Error(`invalid branch spec "${spec}" — expected <type>/<slug> with type in feat, fix, refactor`)
+  }
+  const branchType = value.slice(0, idx)
+  const slug = value.slice(idx + 1)
+  if (!branchValidTypes.has(branchType)) {
+    throw new Error(`invalid branch type "${branchType}" — must be one of feat, fix, refactor`)
+  }
+  if (slug.trim() === '') {
+    throw new Error(`branch slug is required — expected <type>/<slug>, got "${spec}"`)
+  }
+  return { branchType, slug }
+}
+
+/**
+ * defaultGitCheckout runs `git checkout -b <branchName>` with inherited stdio, so Git's own output
+ * (including branch-already-exists errors) reaches the user unmodified.
+ *
+ * Returns Git's own numeric exit code (0 on success), never a generic 1 — this command's contract
+ * is to propagate Git's exit status literally (see internal/commands/branch.go's
+ * defaultGitCheckout, the behavioral reference: it exits the process directly with
+ * exitErr.ExitCode() rather than a hardcoded 1). A spawn failure (e.g. the git binary is missing)
+ * or a signal-terminated process has no Git-produced numeric code to propagate, so both fall back
+ * to 1 — the same convention already used for signal-killed gate commands
+ * (docs/cli-parity.md, `trackfw barrier`, "Gate process terminated by a signal ... Recorded as exit 1").
+ * @param {string} branchName
+ * @returns {number} exit code
+ */
+function defaultGitCheckout(branchName) {
+  const result = spawnSync('git', ['checkout', '-b', branchName], { stdio: 'inherit' })
+  if (result.error) return 1
+  if (result.status === null) return 1
+  return result.status
+}
+
+/**
+ * runBranchNew implements the `trackfw branch new <type>/<slug>` flow described in
+ * docs/req/REQ-2026-08-04-comando-trackfw-branch-new-para-bloquear-criacao-de-branch-sem-req-roadmap-em-wip.md.
+ *
+ * Mirrors Go's stdout/stderr split exactly (internal/commands/branch.go + root.go Execute()):
+ * the primary governance/dry-run message goes to stdout via `writeln`; usage errors and the
+ * "blocked: ..." wrapper (Go's `Execute()` printing the returned error) go to stderr via
+ * `writeErr`. Git's own output is inherited directly by the child process and is never touched
+ * here.
+ *
+ * @param {string} spec "<type>/<slug>"
+ * @param {boolean} dryRun
+ * @param {{ loadConfig?: function, resolveWIPDirs?: function, resolveDoneDirs?: function,
+ *           matchSlug?: function(string, string[], string[]): {matched: boolean, candidates: string[]},
+ *           execGitCheckout?: function(string): number, writeln?: function(string): void,
+ *           writeErr?: function(string): void }} deps
+ * @returns {number} exit code (0 = success, 1 = blocked/usage error, or Git's own exit code when
+ *   `git checkout -b` fails — propagated literally, never hardcoded)
+ */
+function runBranchNew(spec, dryRun, deps = {}) {
+  const loadConfig = deps.loadConfig || config.load
+  const resolveWIPDirs = deps.resolveWIPDirs || validator.resolveWIPDirs
+  const resolveDoneDirs = deps.resolveDoneDirs || validator.resolveDoneDirs
+  const matchSlug = deps.matchSlug || validator.branchSlugMatchesRoadmap
+  const execGitCheckout = deps.execGitCheckout || defaultGitCheckout
+  const writeln = deps.writeln || ((s) => process.stdout.write(s + '\n'))
+  const writeErr = deps.writeErr || ((s) => process.stderr.write(s + '\n'))
+
+  let branchType, slug
+  try {
+    ({ branchType, slug } = parseBranchSpec(spec))
+  } catch (err) {
+    writeErr(err.message)
+    return 1
+  }
+
+  const branchName = `${branchType}/${slug}`
+
+  const cfg = loadConfig()
+  const wipDirs = resolveWIPDirs(cfg)
+  const doneDirs = resolveDoneDirs(cfg)
+
+  const normalizedSlug = validator.normalizeBranchSlug(slug)
+  const { matched, candidates } = matchSlug(normalizedSlug, wipDirs, doneDirs)
+
+  if (!matched) {
+    const msg = (!candidates || candidates.length === 0)
+      ? validator.branchGovernanceOrientation(branchName)
+      : validator.branchNoMatchingRoadmapMessage(branchName, candidates)
+    if (dryRun) {
+      writeln(`[dry-run] would block: ${msg}`)
+    } else {
+      writeln(msg)
+    }
+    writeErr(`blocked: no matching roadmap in wip/ nor done/ for "${branchName}"`)
+    return 1
+  }
+
+  if (dryRun) {
+    writeln(`[dry-run] would create branch "${branchName}" (git checkout -b ${branchName})`)
+    return 0
+  }
+
+  // Git's own stderr (inherited stdio) already reached the user unmodified — do not reformat,
+  // duplicate, or replace this exit code with a generic 1.
+  return execGitCheckout(branchName)
+}
+
+module.exports = {
+  branchValidTypes,
+  parseBranchSpec,
+  defaultGitCheckout,
+  runBranchNew,
+}

package/src/commands/branch.js

@@ -0,0 +1,46 @@
+'use strict'
+
+// trackfw branch new <type>/<slug>
+//
+// CLI wiring for the `trackfw branch` command group. The testable logic lives in
+// ../branch/runner.js (mirrors the ship.js / ship/runner.js split already used in this CLI).
+
+const { Command } = require('commander')
+const { runBranchNew } = require('../branch/runner')
+
+function createBranchCommand() {
+  const cmd = new Command('branch')
+  cmd.description('Manage governed feature branches')
+
+  const newCmd = new Command('new')
+  newCmd
+    .description(
+      'Create a feat/fix/refactor branch, gated on a matching REQ + roadmap already in wip/ or done/\n\n' +
+      'trackfw branch new moves the branch_has_wip_roadmap governance gate (already enforced\n' +
+      "by 'trackfw validate' and 'trackfw ship') to before branch creation, instead of after:\n\n" +
+      '  1. Validates <type> is one of feat, fix, refactor and <slug> is non-empty.\n' +
+      '  2. Checks whether a roadmap in wip/ or done/ matches the given slug — the exact matching\n' +
+      "     logic 'trackfw validate' already uses (normalized slug, filename contains match).\n" +
+      "  3. Without a match: blocks — 'git checkout -b' is never executed — and prints the same\n" +
+      "     governance orientation message 'trackfw validate' already prints for this rule.\n" +
+      "  4. With a match: runs 'git checkout -b <type>/<slug>', propagating Git's own output and\n" +
+      '     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 roadmap move <name> wip'
+    )
+    .argument('<spec>', '<type>/<slug>, type in feat, fix, refactor')
+    .option('--dry-run', 'Report whether the branch would be created or blocked, without executing git', false)
+    .action((spec, options) => {
+      const exitCode = runBranchNew(spec, !!options.dryRun, {})
+      if (exitCode !== 0) {
+        process.exit(exitCode)
+      }
+    })
+
+  cmd.addCommand(newCmd)
+  return cmd
+}
+
+module.exports = createBranchCommand()

package/src/commands/discover.js

@@ -435,6 +435,12 @@ cmd.action((opts) => {
       } catch (e) {
         console.log(`⚠ agent rules inject partial: ${e.message}`);
       }
+      try {
+        const { generateAttentionScripts } = require('../generators/hooks');
+        generateAttentionScripts({}, cwd);
+      } catch (e) {
+        console.warn(`⚠ attention scripts: ${e.message}`);
+      }
       try {
         const { injectHooksDetected } = require('../generators/hooks');
         injectHooksDetected(cwd);

package/src/commands/index.js

@@ -32,6 +32,7 @@ function createProgram() {
   program.addCommand(require('./note'))
   program.addCommand(require('./ship'))
   program.addCommand(require('./barrier'))
+  program.addCommand(require('./branch'))
 
   const { createServeCommand } = require('./serve')
   program.addCommand(createServeCommand())

package/src/commands/init.js

@@ -8,7 +8,7 @@ const { resolveScope } = require('./integrations')
 
 const cmd = new Command('init')
 cmd.description(t('init.description'))
-cmd.option('--ai-tools <tools>', 'Comma-separated AI tools to configure (claude,codex,gemini,antigravity,cursor,copilot,windsurf,amazonq,kiro)', '')
+cmd.option('--ai-tools <tools>', 'Comma-separated AI tools to configure (claude,codex,gemini,antigravity,cursor,copilot,windsurf,amazonq,opencode,kiro)', '')
 cmd.option('--identity-preset <preset>', `Agent identity preset: none, neutral, ${identityStore.presetNames().join(', ')}`, 'none')
 cmd.option('--forge <value>', 'Forge platform: github, gitlab, bitbucket, azure', '')
 cmd.action(async (options, command) => {
@@ -58,7 +58,7 @@ cmd.action(async (options, command) => {
     }
     await generators.scaffold(cfg)
     const aiTools = String(options.aiTools || '').split(',').map(tool => tool.trim()).filter(Boolean)
-    const supported = new Set(['claude', 'codex', 'gemini', 'antigravity', 'cursor', 'copilot', 'windsurf', 'amazonq', 'kiro'])
+    const supported = new Set(['claude', 'codex', 'gemini', 'antigravity', 'cursor', 'copilot', 'windsurf', 'amazonq', 'opencode', 'kiro'])
     // Sem TTY, o escopo nunca é perguntado: default `global` (ADR D1/D4).
     const scope = await resolveScope({}, { interactive: false })
     const makeOnSkip = () => (_destination, reason) => {
@@ -222,6 +222,7 @@ cmd.action(async (options, command) => {
         { name: 'GitHub Copilot', value: 'copilot' },
         { name: 'Windsurf', value: 'windsurf' },
         { name: 'Amazon Q Developer', value: 'amazonq' },
+        { name: 'OpenCode', value: 'opencode' },
         { name: 'Kiro', value: 'kiro' },
       ],
     })

package/src/generators/hooks.js

@@ -82,8 +82,9 @@ case "$ROADMAP_DIR" in
 esac
 
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-TOOL_ESC=$(echo "$TOOL" | tr -d '\\000-\\037' | sed -e 's/\\\\/\\\\\\\\/g' -e 's/"/\\\\"/g')
-MSG_ESC=$(echo "$MSG" | tr -d '\\000-\\037' | sed -e 's/\\\\/\\\\\\\\/g' -e 's/"/\\\\"/g')
+
+TOOL_ESC=$(echo "$TOOL" | tr -d '\\000-\\037' | sed 's/\\\\/\\\\\\\\/g; s/"/\\\\"/g')
+MSG_ESC=$(echo "$MSG" | tr -d '\\000-\\037' | sed 's/\\\\/\\\\\\\\/g; s/"/\\\\"/g')
 
 mkdir -p "$ROADMAP_DIR"
 printf '{"tool":"%s","message":"%s","level":"action_required","timestamp":"%s"}\\n' \\

package/src/integrations/assets/agents/architect.md

@@ -35,6 +35,9 @@ Analyze real dependencies between microbatches before assigning work. Microbatch
 ## Workflow
 Analyze the codebase and requirements; record material decisions in an ADR; create the REQ with an explicit negative scope; produce a roadmap of waves and microbatches with measurable acceptance criteria; create the branch; commit the governance artifacts before any handoff; dispatch the wave; audit each microbatch against its acceptance criteria; update the roadmap; open the pull request only on request.
 
+## Dispatch contract
+Naming a specialist in prose or in a roadmap's `squad:` field is documentation, not delegation — it does not route the Agent tool call by itself. Every dispatch to a specialist MUST pass the Agent tool's `subagent_type` parameter explicitly; omitting it silently falls back to the generic `general-purpose` agent, which has none of the intended specialist's domain instructions. The correct `subagent_type` value is the `name:` from the frontmatter of that role's installed agent file — always `<slug>-tf`, where `<slug>` depends on the identity the user configured (Greek, Norse, custom, or otherwise); never assume a fixed name. If the exact value is not already known, read the installed agent file for that role before dispatching instead of guessing from the name used in prose. Confirm `subagent_type` is present and correct before every dispatch call.
+
 ## Post-microbatch audit
 Before releasing the next wave, verify each acceptance criterion yourself: read the changed files, confirm the build, tests and gates, and check that no forbidden file was touched. Green gates are not proof that the intended behavior was delivered — validate the real artifact, not only the test fixtures. A failed audit blocks the next wave.
 

package/src/integrations/assets/catalog.json

@@ -42,6 +42,7 @@
     {"id":"copilot","name":"GitHub Copilot","surfaces":[{"id":"ide","name":"GitHub Copilot","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"custom-agent"},"skills":{"support_level":"native","representation":"agent-skill"}},"paths":{"agents":[{"scope":"global","path":"~/.copilot/agents/trackfw-{{id}}.agent.md","extension":".agent.md"},{"scope":"project","path":".github/agents/trackfw-{{id}}.agent.md","extension":".agent.md"}],"skills":[{"scope":"global","path":"~/.copilot/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".github/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"instructions","surface":"ide","scope":"project","path":".github/copilot-instructions.md","purpose":"repository instructions","required":false},{"id":"hooks","surface":"ide","scope":"project","path":".github/hooks/trackfw-attention.json","purpose":"attention hooks","required":false}]},
     {"id":"windsurf","name":"Windsurf","surfaces":[{"id":"ide","name":"Windsurf IDE","scopes":["global","project"],"capabilities":{"agents":{"support_level":"fallback","representation":"skill","fallback_representation":"specialist skill"},"skills":{"support_level":"native","representation":"skill"}},"paths":{"agents":[{"scope":"global","path":"~/.codeium/windsurf/skills/trackfw-agent-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".windsurf/skills/trackfw-agent-{{id}}/SKILL.md","extension":".md"}],"skills":[{"scope":"global","path":"~/.codeium/windsurf/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".windsurf/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"global-rules","surface":"ide","scope":"project","path":".windsurfrules","purpose":"governance rule discovery","required":false}]},
     {"id":"amazonq","name":"Amazon Q Developer","surfaces":[{"id":"cli","name":"Amazon Q Developer CLI","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"cli-agent-json"},"skills":{"support_level":"fallback","representation":"rule","fallback_representation":"workflow rule"}},"paths":{"agents":[{"scope":"global","path":"~/.aws/amazonq/cli-agents/trackfw-{{id}}.json","extension":".json"},{"scope":"project","path":".amazonq/cli-agents/trackfw-{{id}}.json","extension":".json"}],"skills":[{"scope":"global","path":"~/.aws/amazonq/rules/trackfw-{{id}}.md","extension":".md"},{"scope":"project","path":".amazonq/rules/trackfw-{{id}}.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"guidelines","surface":"cli","scope":"project","path":".amazonq/developer/guidelines.md","purpose":"project governance guidelines","required":false}]},
+    {"id":"opencode","name":"OpenCode","surfaces":[{"id":"cli","name":"OpenCode CLI","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"opencode-agent"},"skills":{"support_level":"native","representation":"skill"}},"paths":{"agents":[{"scope":"global","path":"~/.config/opencode/agents/trackfw-{{id}}.md","extension":".md"},{"scope":"project","path":".opencode/agents/trackfw-{{id}}.md","extension":".md"}],"skills":[{"scope":"global","path":"~/.config/opencode/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".opencode/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"instructions","surface":"cli","scope":"project","path":"AGENTS.md","purpose":"repository instructions (shared with Codex/AGENTS.md convention)","required":false}]},
     {"id":"kiro","name":"Kiro","surfaces":[{"id":"ide","name":"Kiro IDE","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"agent-markdown"},"skills":{"support_level":"native","representation":"agent-skill"}},"paths":{"agents":[{"scope":"global","path":"~/.kiro/agents/trackfw-{{id}}.md","extension":".md"},{"scope":"project","path":".kiro/agents/trackfw-{{id}}.md","extension":".md"}],"skills":[{"scope":"global","path":"~/.kiro/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".kiro/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}},{"id":"cli","name":"Kiro CLI","scopes":["global","project"],"capabilities":{"agents":{"support_level":"native","representation":"agent-json"},"skills":{"support_level":"native","representation":"agent-skill"}},"paths":{"agents":[{"scope":"global","path":"~/.kiro/agents/trackfw-{{id}}.json","extension":".json"},{"scope":"project","path":".kiro/agents/trackfw-{{id}}.json","extension":".json"}],"skills":[{"scope":"global","path":"~/.kiro/skills/trackfw-{{id}}/SKILL.md","extension":".md"},{"scope":"project","path":".kiro/skills/trackfw-{{id}}/SKILL.md","extension":".md"}]}}],"auxiliary_artifacts":[{"id":"hooks","surface":"ide","scope":"project","path":".kiro/hooks/trackfw-attention.json","purpose":"attention hooks","required":false}]}
   ]
 }

package/src/integrations/render.js

@@ -278,6 +278,38 @@ function render({ kind, content, capability, item, identity: cfg }) {
     return out
   }
 
+  if (capability.representation === 'opencode-agent') {
+    // Reconstrói o frontmatter para o OpenCode CLI (opencode.ai), seguindo o
+    // mesmo padrão de reconstrução-do-zero do case "agent-directory".
+    // Decisão registrada na Wave 1 do roadmap
+    // ROADMAP-2026-08-04-compatibilidade-com-opencode-opencode-ai (achado #3,
+    // pesquisa contra o binário real 1.18.13):
+    //   - "tools:" é uma chave RESERVADA no schema de agente do OpenCode
+    //     (espera um objeto de overrides por-ferramenta, ex. {bash: false},
+    //     não uma lista de nomes estilo Claude Code) — reutilizar o
+    //     frontmatter original faz o OpenCode recusar o carregamento INTEIRO
+    //     do projeto ("Configuration is invalid"), não só daquele agente. Por
+    //     isso "tools:" nunca é emitido aqui.
+    //   - sem "mode:" explícito, o OpenCode assume mode "all" (agente
+    //     selecionável como persona primária de chat) — os agentes trackfw
+    //     devem ser sempre subagentes puros, nunca primários, para paridade
+    //     com o comportamento nos demais targets. Por isso "mode: subagent" é
+    //     sempre fixo, nunca omitido.
+    //   - "model:" é deliberadamente OMITIDO (decisão de produto do
+    //     orquestrador, não uma limitação técnica): o OpenCode espera
+    //     "provider/model-id" (ex. "anthropic/claude-sonnet-4-5"), não os
+    //     aliases curtos do catálogo canônico ("opus"/"sonnet"), e mapear
+    //     para um provider fixo contradiria a motivação de negócio do REQ
+    //     (permitir que o usuário roteie os agentes trackfw para o modelo
+    //     open-source/local que ele já configurou em opencode.json). Omitir
+    //     deixa o OpenCode resolver pelo default já configurado pelo usuário.
+    //   - "memory:" também não faz sentido no schema do OpenCode e é
+    //     descartado junto com "tools:".
+    let out = `---\ndescription: ${description}\nmode: subagent\n---\n`
+    if (body) out += `${body}\n`
+    return out
+  }
+
   if (!id) return normalize(content)
   const withBody = insertBodyPrefix(content, greeting)
   const withFrontmatter = rewriteFrontmatterFields(withBody, name, description)

package/src/validator/index.js

@@ -1042,6 +1042,45 @@ function validateFilenameUniqueness() {
   return violations
 }
 
+// branchSlugMatchesRoadmap verifica se branchSlug (já normalizado via normalizeBranchSlug) casa com o
+// nome de algum roadmap .md encontrado em wipDirs ou doneDirs. Reutilizada por
+// validateBranchHasWIPRoadmap e pelo comando `trackfw branch new` — nunca duplicar esta lógica.
+//
+// Espelha internal/validator/validator.go:BranchSlugMatchesRoadmap. Retorna { matched, candidates }:
+// matched indica se algum candidato casou com o slug; candidates lista todos os roadmaps .md
+// encontrados em wipDirs+doneDirs (para diagnóstico/mensagem de orientação quando matched é false).
+function branchSlugMatchesRoadmap(branchSlug, wipDirs, doneDirs) {
+  const dirs = [...wipDirs, ...doneDirs]
+  const candidates = []
+  let matched = false
+  for (const dir of dirs) {
+    const files = listDir(dir).filter(f => f.endsWith('.md'))
+    candidates.push(...files)
+    if (files.some(file => normalizeBranchSlug(file).includes(branchSlug))) matched = true
+  }
+  return { matched, candidates }
+}
+
+// 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`
+}
+
+// branchNoMatchingRoadmapMessage is the guidance message printed when roadmaps exist in wip/ or
+// done/ but none of them match the branch's slug. Shared by validateBranchHasWIPRoadmap and
+// `trackfw branch new` — never duplicate this string. Byte-identical to Go's
+// BranchNoMatchingRoadmapMessage. Does not mutate candidates.
+function branchNoMatchingRoadmapMessage(branch, candidates) {
+  // P3: sort for deterministic output regardless of filesystem ordering.
+  const sorted = [...candidates].sort()
+  const display = sorted.slice(0, 3)
+  const suffix = sorted.length > 3 ? `, e mais ${sorted.length - 3}` : ''
+  return `branch "${branch}" has no matching roadmap in wip/ nor done/ (found: ${display.join(', ')}${suffix}) — include the branch slug in the roadmap filename or set TRACKFW_BRANCH explicitly in CI`
+}
+
 // validateBranchHasWIPRoadmap — verifica que branch feat/fix/refactor tem ao menos um roadmap em
 // wip/ ou done/ cujo slug case com a branch. Aceita done/ para permitir encerramento do roadmap na
 // própria branch, conforme a Definition of Done, sem reprovar o gate.
@@ -1067,22 +1106,13 @@ function validateBranchHasWIPRoadmap() {
   const wipDirs = resolveWIPDirs(cfg)
   const doneDirs = resolveDoneDirs(cfg)
   const branchSlug = normalizeBranchSlug(branch.split('/', 2)[1])
-  // candidates reúne todos os roadmaps encontrados em wip/ e done/.
-  const candidates = []
-  for (const dir of [...wipDirs, ...doneDirs]) {
-    const files = listDir(dir).filter(f => f.endsWith('.md'))
-    candidates.push(...files)
-    if (files.some(file => normalizeBranchSlug(file).includes(branchSlug))) return []
-  }
+  const { matched, candidates } = branchSlugMatchesRoadmap(branchSlug, wipDirs, doneDirs)
+  if (matched) return []
 
   if (candidates.length === 0) {
-    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`]
+    return [branchGovernanceOrientation(branch)]
   }
-  // P3: sort for deterministic output regardless of filesystem ordering.
-  const sorted = [...candidates].sort()
-  const display = sorted.slice(0, 3)
-  const suffix = sorted.length > 3 ? `, e mais ${sorted.length - 3}` : ''
-  return [`branch "${branch}" has no matching roadmap in wip/ nor done/ (found: ${display.join(', ')}${suffix}) — include the branch slug in the roadmap filename or set TRACKFW_BRANCH explicitly in CI`]
+  return [branchNoMatchingRoadmapMessage(branch, candidates)]
 }
 
 function normalizeBranchSlug(value) {
@@ -1451,6 +1481,11 @@ module.exports = {
   validateFolderStatusCoherence,
   validateFilenameUniqueness,
   validateBranchHasWIPRoadmap,
+  // novas funções — trackfw branch new (extraídas do gate branch_has_wip_roadmap)
+  branchSlugMatchesRoadmap,
+  branchGovernanceOrientation,
+  branchNoMatchingRoadmapMessage,
+  normalizeBranchSlug,
   // novas funções ML-2B
   contentHasMarker,
   ruleSeverity,