trackfw 6.3.0 → 6.4.0

package/README.md

@@ -144,7 +144,8 @@ trackfw ship -m "feat(auth): add login flow"
 | `trackfw adr new "title"` | Create a new Architecture Decision Record |
 | `trackfw adr list` | List all ADRs with status |
 | `trackfw req new "title"` | Create a REQ with guided ADR discovery |
-| `trackfw req list` | List all REQs with status |
+| `trackfw req list` | List all REQs with status, discovered across flat, per-state, and by_agent layouts |
+| `trackfw req move <name> <status>` | Update a REQ's status; physically relocates the file when it already lives in a recognized state subfolder (see [Multi-agent namespacing](#multi-agent-namespacing)) |
 | `trackfw roadmap new "title"` | Create a roadmap in `backlog/` |
 | `trackfw roadmap show <name>` | Print a roadmap with its current state |
 | `trackfw roadmap move <name> <state>` | Move roadmap between states |
@@ -210,6 +211,29 @@ agents: [claude, gemini, copilot]
 
 Artifacts are organized by agent: `docs/roadmaps/claude/wip/`, `docs/req/gemini/done/`. `trackfw validate` and `trackfw context` are fully by_agent-aware — no false positives.
 
+REQs reuse this same `roadmap_namespacing` setting — there is no separate `req_namespacing` key. When
+`by_agent` is configured, REQs may live under `req_dir/<agent>/<state>/` just like roadmaps do.
+
+`trackfw req list` and `trackfw req move` discover REQs across three layouts at once (each is a fixed,
+non-recursive glob — a REQ nested deeper than these patterns is not found), with no extra flag required:
+
+- **Flat (legacy):** `req_dir/*.md` — REQs loose directly in the REQ directory.
+- **Per-state:** `req_dir/<state>/*.md` — organized by state, without an agent segment.
+- **By agent:** `req_dir/<agent>/<state>/*.md` — used when `roadmap_namespacing: by_agent` is set.
+
+`trackfw req move <name> <status>` behaves conditionally depending on where the REQ currently lives:
+
+- If the REQ already sits inside a recognized state subfolder (per-state or by_agent layout above), the
+  move **physically relocates the file** to the target state's folder, mirroring `trackfw roadmap move` —
+  the folder is the source of truth for state. In this mode `<status>` must be one of the six governance
+  states (`backlog`, `analyzing`, `wip`, `blocked`, `done`, `abandoned`) — any other value is rejected
+  with `invalid state`.
+- If the REQ is loose in `req_dir/` (flat legacy layout), the move rewrites the `status:` frontmatter
+  field **in place** and does not move or create any folder. `<status>` is written verbatim in this
+  mode — it accepts the free-form values existing REQs already use (`Open`, `Done`, ...), not just the
+  six governance state names. Existing flat REQs are never migrated automatically — you are not forced
+  to reorganize a project's existing REQs to adopt this behavior.
+
 ### Bidirectional traceability (`trace_id_field`)
 
 ```yaml

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "trackfw",
-  "version": "6.3.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, 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/commands/req.js

@@ -64,13 +64,18 @@ cmd.command('new <title>')
 cmd.command('list')
   .description(t('req.list.description'))
   .action(async () => {
-    listREQs(require('../config').load().reqDir)
+    listREQs(require('../config').load())
   })
 
 cmd.command('move <name> <status>')
   .description('Update a REQ status in place')
   .action(async (name, status) => {
-    moveREQ(name, status)
+    try {
+      moveREQ(name, status)
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exitCode = 1
+    }
   })
 
 module.exports = cmd

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/generators/req.js

@@ -2,27 +2,86 @@
 const fs = require('fs')
 const path = require('path')
 const { localDateISO } = require('./date')
+const roadmapGen = require('./roadmap')
+const config = require('../config')
+
+const VALID_STATES = roadmapGen.VALID_STATES
+const STATE_ORDER = roadmapGen.STATE_ORDER
 
 /**
- * listREQs — lista arquivos .md em dir, imprimindo filename e status (coluna 60 chars).
- * Extrai status da linha `> Date: ... | Status: ...`.
- * Se dir não existe ou vazio: imprime "No REQs found in <dir>".
+ * listREQFiles — descoberta recursiva de REQs nos 3 layouts suportados, mesmo algoritmo usado
+ * em Go/Python (ADR-2026-08-04): flat (reqDir/*.md), por-estado (reqDir/<estado>/*.md) e,
+ * quando roadmapNamespacing === 'by_agent', by_agent (reqDir/<agente>/<estado>/*.md).
+ * Os três conjuntos não são mutuamente exclusivos — concatena todos.
+ * @param {object} cfg — config completo (ver npm/src/config)
+ * @returns {string[]} paths completos, na ordem flat → por-estado → by_agent
  */
-function listREQs(dir) {
-  let files = []
+function listREQFiles(cfg) {
+  const reqDir = cfg.reqDir
+  const files = []
+
+  // (a) flat legado — reqDir/*.md
   try {
-    files = fs.readdirSync(dir).filter(f => f.endsWith('.md'))
-  } catch (_) {
-    // dir não existe
+    for (const f of fs.readdirSync(reqDir)) {
+      if (!f.endsWith('.md')) continue
+      const full = path.join(reqDir, f)
+      try {
+        if (!fs.statSync(full).isDirectory()) files.push(full)
+      } catch (_) { /* ignora */ }
+    }
+  } catch (_) { /* reqDir não existe */ }
+
+  // (b) por-estado, sem agente — reqDir/<estado>/*.md
+  for (const state of STATE_ORDER) {
+    const dir = path.join(reqDir, state)
+    try {
+      for (const f of fs.readdirSync(dir)) {
+        if (f.endsWith('.md')) files.push(path.join(dir, f))
+      }
+    } catch (_) { /* estado não existe */ }
+  }
+
+  // (c) by_agent — reqDir/<agente>/<estado>/*.md
+  if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
+    let agents = cfg.agents || []
+    if (agents.length === 0) {
+      try {
+        agents = fs.readdirSync(reqDir).filter(f => {
+          try { return fs.statSync(path.join(reqDir, f)).isDirectory() } catch (_) { return false }
+        })
+      } catch (_) { agents = [] }
+    }
+    for (const agent of agents) {
+      for (const state of STATE_ORDER) {
+        const dir = path.join(reqDir, agent, state)
+        try {
+          for (const f of fs.readdirSync(dir)) {
+            if (f.endsWith('.md')) files.push(path.join(dir, f))
+          }
+        } catch (_) { /* agente/estado não existe */ }
+      }
+    }
   }
 
+  return files
+}
+
+/**
+ * listREQs — lista REQs (recursivo nos 3 layouts), imprimindo filename e status (coluna 60 chars).
+ * Extrai status da linha `> Date: ... | Status: ...`.
+ * Se nenhum REQ encontrado: imprime "No REQs found in <reqDir>".
+ * @param {object} cfg — config completo (ver npm/src/config)
+ */
+function listREQs(cfg) {
+  const files = listREQFiles(cfg)
+
   if (files.length === 0) {
-    console.log(`No REQs found in ${dir}`)
+    console.log(`No REQs found in ${cfg.reqDir}`)
     return
   }
 
-  for (const filename of files) {
-    const filepath = path.join(dir, filename)
+  for (const filepath of files) {
+    const filename = path.basename(filepath)
     const status = parseREQStatus(filepath)
     console.log(`${filename.padEnd(60)} ${status}`)
   }
@@ -105,30 +164,105 @@ function rewriteREQStatus(source, status) {
   return { content: `---\n${lines.join('\n')}${rest}`, changed: true }
 }
 
-function findREQ(name, reqDir) {
-  let files = []
-  try {
-    files = fs.readdirSync(reqDir).filter(f => f.endsWith('.md'))
-  } catch (e) {
-    throw new Error(`reading REQ dir: ${e.message}`)
-  }
+/**
+ * findREQ — busca recursiva nos 3 layouts (flat → por-estado → by_agent), retornando o primeiro
+ * path cujo basename contém `name` (case-insensitive).
+ * @param {string} name
+ * @param {object} cfg — config completo (ver npm/src/config)
+ * @returns {string} path completo
+ */
+function findREQ(name, cfg) {
+  const files = listREQFiles(cfg)
   const lower = name.toLowerCase()
-  const found = files.find(f => f.toLowerCase().includes(lower))
-  if (!found) throw new Error(`REQ "${name}" not found in ${reqDir}`)
-  return path.join(reqDir, found)
+  const found = files.find(f => path.basename(f).toLowerCase().includes(lower))
+  if (!found) throw new Error(`REQ "${name}" not found in ${cfg.reqDir}`)
+  return found
 }
 
+/**
+ * appendREQTransitionLog — append em <reqDir>/.trackfw-log, mesmo formato de
+ * appendTransitionLog (roadmap.js), em arquivo de log separado (escopo de REQ, não roadmap).
+ */
+function appendREQTransitionLog(cfg, basename, fromState, toState) {
+  const now = new Date()
+  const yyyy = now.getFullYear()
+  const mm = String(now.getMonth() + 1).padStart(2, '0')
+  const dd = String(now.getDate()).padStart(2, '0')
+  const hh = String(now.getHours()).padStart(2, '0')
+  const min = String(now.getMinutes()).padStart(2, '0')
+  const timestamp = `${yyyy}-${mm}-${dd} ${hh}:${min}`
+  const line = `${timestamp}  ${basename.padEnd(50)}  ${fromState} → ${toState}\n`
+
+  try {
+    const lp = path.join(cfg.reqDir, '.trackfw-log')
+    fs.mkdirSync(path.dirname(lp), { recursive: true })
+    fs.appendFileSync(lp, line, 'utf8')
+  } catch (_) { /* best-effort, mesmo padrão do roadmap */ }
+}
+
+/**
+ * moveREQ — reescreve status: e, condicionalmente, move fisicamente o arquivo
+ * (ADR-2026-08-04, decisão D3):
+ * - REQ solta em `reqDir/` → modo in-place (comportamento legado: só reescreve status, sem mover).
+ * - REQ já organizada em `reqDir/<estado>/` ou `reqDir/<agente>/<estado>/` → move fisicamente
+ *   para o novo estado, preservando o layout (por-estado ou by_agent), e loga a transição.
+ */
 function moveREQ(name, status) {
   if (!String(status || '').trim()) throw new Error('status is required')
-  const reqDir = require('../config').load().reqDir
-  const filepath = findREQ(name, reqDir)
+  const cfg = require('../config').load()
+  const filepath = findREQ(name, cfg)
   const source = fs.readFileSync(filepath, 'utf8')
   const result = rewriteREQStatus(source, status)
   if (!result.changed) {
     throw new Error(`REQ "${path.basename(filepath)}" has no frontmatter status/header Status to update`)
   }
-  fs.writeFileSync(filepath, result.content, 'utf8')
-  console.log(`✓ updated ${path.basename(filepath)} status → ${status}`)
+
+  const basename = path.basename(filepath)
+  const parentDir = path.dirname(filepath)
+  const grandparentDir = path.dirname(parentDir)
+  const greatGrandparentDir = path.dirname(grandparentDir)
+  const reqDirAbs = path.resolve(cfg.reqDir)
+  const fromState = path.basename(parentDir)
+
+  if (path.resolve(parentDir) === reqDirAbs) {
+    // modo in-place — REQ solta em reqDir/, comportamento legado (sem mover)
+    fs.writeFileSync(filepath, result.content, 'utf8')
+    console.log(`✓ updated ${basename} status → ${status}`)
+    return
+  }
+
+  if (!VALID_STATES.includes(status)) {
+    throw new Error(`invalid state "${status}" — valid states: ${VALID_STATES.join(', ')}`)
+  }
+
+  let targetDir = null
+  let logBasename = basename
+
+  if (path.resolve(grandparentDir) === reqDirAbs && VALID_STATES.includes(fromState)) {
+    // layout por-estado — reqDir/<estado>/
+    targetDir = path.join(cfg.reqDir, status)
+  } else if (VALID_STATES.includes(fromState) && path.resolve(greatGrandparentDir) === reqDirAbs) {
+    // layout by_agent — reqDir/<agente>/<estado>/
+    const agent = path.basename(grandparentDir)
+    targetDir = path.join(cfg.reqDir, agent, status)
+    logBasename = `${agent}/${basename}`
+  }
+
+  if (!targetDir) {
+    // layout não reconhecido — fallback seguro para in-place (não inventa destino)
+    fs.writeFileSync(filepath, result.content, 'utf8')
+    console.log(`✓ updated ${basename} status → ${status}`)
+    return
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true })
+  const dst = path.join(targetDir, basename)
+  fs.writeFileSync(dst, result.content, 'utf8')
+  if (path.resolve(dst) !== path.resolve(filepath)) {
+    fs.unlinkSync(filepath)
+  }
+  appendREQTransitionLog(cfg, logBasename, fromState, status)
+  console.log(`✓ moved ${basename} → ${targetDir}`)
 }
 
 /**
@@ -328,4 +462,4 @@ function detectDomains(intention) {
   )
 }
 
-module.exports = { listREQs, parseREQStatus, rewriteREQStatus, moveREQ, newREQ, PROBES_CATALOG, detectDomains, localDateISO, toSlug }
+module.exports = { listREQs, listREQFiles, findREQ, parseREQStatus, rewriteREQStatus, moveREQ, newREQ, PROBES_CATALOG, detectDomains, localDateISO, toSlug }

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,