trackfw 3.1.0 → 5.0.0

package/src/generators/init.js

@@ -101,13 +101,26 @@ roadmap_namespacing: flat
 // scripts/trackfw-validate.sh
 // ---------------------------------------------------------------------------
 
-function generateValidateScript(cfg) {
-  fs.mkdirSync('scripts', { recursive: true })
+// generateValidateScript — cwd is optional and defaults to process.cwd() so
+// existing callers (scaffold(), which always runs with process.cwd() already
+// at the project root) keep working unchanged. `trackfw update`'s
+// validate-script target passes cwd explicitly so this can be applied
+// against a --dry-run sandbox root without ever touching the real project
+// tree — this is the SAME canonical generator scaffold() uses for `init`,
+// not a separate copy (see npm/src/commands/discover.js's writeValidateScript,
+// which is a different, simpler generator used only by `discover`/legacy
+// paths and must never be reused here — that mismatch was the ML-6H
+// validate-script parity bug: init wrote the rich per-backend script,
+// `update` overwrote it with the static 3-line one, so idempotent re-runs
+// reported "updated" instead of "skipped").
+function generateValidateScript(cfg, cwd) {
+  const root = cwd || process.cwd()
+  fs.mkdirSync(path.join(root, 'scripts'), { recursive: true })
 
   const script = buildValidateScript(cfg)
-  const scriptPath = path.join('scripts', 'trackfw-validate.sh')
+  const scriptPath = path.join(root, 'scripts', 'trackfw-validate.sh')
   fs.writeFileSync(scriptPath, script, { encoding: 'utf8', mode: 0o755 })
-  console.log(`  ✓ ${scriptPath}`)
+  console.log(`  ✓ ${path.join('scripts', 'trackfw-validate.sh')}`)
 }
 
 function buildValidateScript(cfg) {
@@ -381,14 +394,19 @@ This project uses **trackfw** for AI-native delivery governance.
 Chain: \`ADR → REQ → ROADMAP\` · States: \`backlog / analyzing / wip / blocked / done / abandoned\`
 
 ### Agent Protocol
-1. **Before starting:** run \`trackfw context\` · read \`docs/agents-working-context.md\`
-2. **After finishing:** update \`docs/agents-working-context.md\` with what changed
-3. **Before PR:** \`trackfw validate\` must pass
-4. **ML lifecycle — mandatory:**
+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>\`
+   ❌ 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+)
+2. **Before starting:** run \`trackfw context\` · read \`docs/agents-working-context.md\`
+3. **After finishing:** update \`docs/agents-working-context.md\` with what changed
+4. **Before PR:** \`trackfw validate\` must pass
+5. **ML lifecycle — mandatory:**
    - Starting a ML: edit roadmap \`**Status:** ⬜ Pendente\` → \`**Status:** 🔄 Em andamento\` + commit.
    - Completing a ML: edit roadmap → \`**Status:** ✅ Concluído\` + include in ML commit.
    - Analyzing a roadmap: move from \`backlog/\` to \`analyzing/\`; to \`wip/\` only when coding starts.
-5. **${GLOBAL_ADRS_DIRECTIVE}**
+6. **${GLOBAL_ADRS_DIRECTIVE}**
 
 ### Attention Signal (when you need user input during a task)
 Write \`docs/roadmaps/.trackfw-attention.json\`:
@@ -411,6 +429,13 @@ Delete the file when resolved. Visible as a live banner in \`trackfw serve\`.
 - **Security wave:** include a red-team review wave in every feature roadmap
 - **Test coverage:** TDD for critical logic; min 60% (prototype) / 80% (production)
 - Use \`/trackfw:architect\` to define stack before the first REQ
+
+### Key Commands
+- \`trackfw context\` — current governance state (always run first)
+- \`trackfw status\` — all artifacts and states
+- \`trackfw validate\` — governance consistency check
+- \`trackfw roadmap move <name> <state>\` — transition roadmap state
+- \`trackfw serve\` — live Kanban board at http://localhost:4080
 ` + RULES_END
 }
 
@@ -529,7 +554,8 @@ function generateClaudeMD(cfg) {
   content += '| `/trackfw:roadmap <req>` | Generate AI roadmap from a REQ |\n'
   content += '| `/trackfw:move <name> <state>` | Move roadmap between states manually |\n'
   content += '| `/trackfw:validate` | Run governance validation |\n'
-  content += '| `/trackfw:status` | Check what is in flight |\n\n'
+  content += '| `/trackfw:status` | Check what is in flight |\n'
+  content += '| `/trackfw:barrier` | Run the wave-release checklist before liberating the next wave |\n\n'
 
   content += '## CLI commands (terminal / CI)\n\n'
   content += '| Command | When to use |\n'
@@ -698,14 +724,20 @@ function backendCommands(cfg) {
 }
 
 // ---------------------------------------------------------------------------
-// .claude/commands/trackfw/ — 7 slash commands
+// .claude/commands/trackfw/ — slash commands
+//
+// CLAUDE_COMMANDS is the single source of truth for the set of slash
+// commands installed by trackfw. Both generateClaudeCommands (normal path,
+// idempotent — never overwrites an existing file) and
+// generateClaudeCommandsForce (force path — always overwrites) install
+// from this same map; they only differ in overwrite behavior. This mirrors
+// the Go CLI's installSkillsInner(force) and the Python CLI's single
+// generate_claude_commands — one list, one force flag. Do not fork this map
+// again: a prior divergence let the force path fall behind the normal path
+// (missing roadmap.md, implement.md, barrier.md) undetected.
 // ---------------------------------------------------------------------------
 
-function generateClaudeCommands() {
-  const dir = '.claude/commands/trackfw'
-  fs.mkdirSync(dir, { recursive: true })
-
-  const commands = {
+const CLAUDE_COMMANDS = {
     'adr.md': `Execute o seguinte comando bash: \`trackfw adr new "$ARGUMENTS"\`
 
 Se o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:
@@ -949,6 +981,51 @@ Roadmap: docs/roadmaps/done/<nome>.md
 Próximo passo: abrir PR com gh pr create
 \`\`\``,
 
+    'barrier.md': `Você é o \`trackfw_architect\`, a única autoridade Git deste projeto. Este comando executa o checklist operacional de liberação de uma wave — nenhum outro agente commita, faz push ou libera a próxima wave.
+
+## Argumento
+
+\`$ARGUMENTS\` no formato \`<roadmap> <wave>\`. Se ausente ou incompleto, pergunte ao usuário qual roadmap (em \`docs/roadmaps/wip/\`) e qual número de wave validar.
+
+---
+
+## Núcleo determinístico
+
+Execute primeiro:
+\`\`\`bash
+trackfw barrier <roadmap> --wave <n> --json
+\`\`\`
+
+Este comando é **necessário mas não suficiente**. Ele verifica MLs concluídos, evidências e \`trackfw validate\`, mas não substitui as inspeções especializadas nem a auditoria de diff abaixo — nenhuma delas é avaliada pelo binário. Consulte a seção \`trackfw barrier\` em \`docs/cli-parity.md\` para o contrato completo (estados, exit codes, saída JSON).
+
+Se o comando retornar exit code não-zero (\`blocked\` ou erro de resolução): pare, reporte a falha ao usuário e não prossiga no checklist até que a wave passe.
+
+---
+
+## Definição de pronto da barrier — checklist completo
+
+Antes de liberar a próxima wave, confirme cada item com evidência concreta — não presuma:
+
+1. **Todos os MLs da wave concluídos e marcados** — cada ML da wave está com \`**Status:** ✅ Concluído\` no roadmap.
+2. **Testes unitários e E2E aplicáveis executados** — rode os comandos de validação declarados em cada ML.
+3. **Build aplicável sem erros** — rode o comando de build do(s) workspace(s) afetado(s).
+4. **Cada critério de aceite inspecionado com evidência** — leia os arquivos modificados e confirme contra os critérios listados, não apenas contra os testes.
+5. **Agente code-quality reportou conformidade, performance, robustez e clareza** — invoque o agente \`code-quality\` quando a mudança introduzir lógica nova, duplicação relevante ou risco de manutenibilidade.
+6. **Agente security reportou SAST, privilégios, controle de acesso e camadas aplicáveis** — invoque o agente \`security\` quando a mudança tocar autenticação, segredos, entrada externa ou permissões.
+7. **Gates pré-commit declarados pelo projeto executados** — rode os hooks/gates configurados (lint, format, testes de contrato).
+8. **\`trackfw validate --json\` aprovado** — execute e confirme zero violações.
+9. **Diff auditado contra o escopo** — revise o diff completo; confirme que não há alterações de agentes concorrentes nem arquivos fora do escopo do ML (ex: \`docs/adr/\`, \`docs/req/\`, \`docs/roadmaps/\` quando não autorizado ao especialista).
+10. **Resultado registrado antes de liberar a próxima wave** — anote no roadmap ou na resposta ao usuário que a wave passou, com a evidência de cada item acima.
+
+Se qualquer item falhar: bloqueie a próxima wave, identifique o item e o agente responsável, e despache um microlote corretivo. Só repita o checklist depois que o corretivo for concluído.
+
+---
+
+## Autoridade Git
+
+Somente o \`trackfw_architect\` cria branch, audita diff, commita e faz push. Especialistas entregam trabalho sem commit — cabe a este papel revisar, commitar e sugerir a abertura de PR/MR (sem abrir automaticamente sem autorização do usuário).
+`,
+
     'architect.md': `Você é o guia de arquitetura do trackfw. Ajude o usuário a escolher a stack correta e arquitetar a aplicação em linguagem simples, acessível para times não técnicos.
 
 ## Passo 1 — Descoberta de Negócio
@@ -1027,13 +1104,21 @@ Oriente o usuário:
 2. Gere o roadmap em microlotes com /trackfw:roadmap
 3. Inicie a implementação com /trackfw:implement
 \`\`\``,
-  }
+}
+
+/**
+ * installClaudeCommandsInner — fonte única de escrita dos slash commands.
+ * @param {string} dir diretório de destino (já resolvido)
+ * @param {boolean} force quando true, sobrescreve arquivos existentes
+ */
+function installClaudeCommandsInner(dir, force) {
+  fs.mkdirSync(dir, { recursive: true })
 
   let created = 0
   let skipped = 0
-  for (const [filename, content] of Object.entries(commands)) {
+  for (const [filename, content] of Object.entries(CLAUDE_COMMANDS)) {
     const filePath = path.join(dir, filename)
-    if (fs.existsSync(filePath)) {
+    if (!force && fs.existsSync(filePath)) {
       skipped++
       continue
     }
@@ -1041,13 +1126,28 @@ Oriente o usuário:
     created++
   }
 
-  if (skipped > 0) {
+  if (force) {
+    console.log(`  ✓ ${dir} (${created} slash commands sobrescritos)`)
+  } else if (skipped > 0) {
     console.log(`  ✓ ${dir} (${created} slash commands criados, ${skipped} já existiam — não sobrescritos)`)
   } else {
     console.log(`  ✓ ${dir} (${created} slash commands)`)
   }
 }
 
+/**
+ * generateClaudeCommands — instala os slash commands de forma idempotente:
+ * nunca sobrescreve um arquivo já existente. Honra o `rootDir` recebido
+ * (mesma convenção do gêmeo forçado generateClaudeCommandsForce e do
+ * generate_claude_commands(cwd) do Python); quando omitido, cai no
+ * caminho relativo ao cwd do processo, preservando o comportamento
+ * histórico consumido pelos testes que chamam sem argumento.
+ */
+function generateClaudeCommands(rootDir) {
+  const dir = rootDir ? path.join(rootDir, '.claude', 'commands', 'trackfw') : '.claude/commands/trackfw'
+  installClaudeCommandsInner(dir, false)
+}
+
 // ---------------------------------------------------------------------------
 // AI tool installers
 // ---------------------------------------------------------------------------
@@ -1117,10 +1217,10 @@ async function installAmazonQ(cwd = process.cwd()) {
  * resolved (ADR-2026-07-25-escopo-de-instalacao-selecionavel-para-agents-e-
  * skills, D4).
  */
-async function installIntegrationTarget(target, cwd = process.cwd(), scope = 'project') {
+async function installIntegrationTarget(target, cwd = process.cwd(), scope = 'project', { onSkip } = {}) {
   const { execute, buildPlans } = require('../integrations')
   const roots = { projectRoot: cwd }
-  const options = { targets: [target], scope }
+  const options = { targets: [target], scope, onSkip }
   // D5 — transparency: print resolved destinations before writing anything.
   // buildPlans has no side effects, so it is safe to call here purely to
   // enumerate destinations; the actual write happens below via execute().
@@ -1140,25 +1240,13 @@ async function installIntegrationTarget(target, cwd = process.cwd(), scope = 'pr
 }
 
 /**
- * generateClaudeCommandsForce — re-gera todos os slash commands, sobrescrevendo arquivos existentes.
+ * generateClaudeCommandsForce — re-gera todos os slash commands, sobrescrevendo
+ * arquivos existentes. Instala exatamente o mesmo conjunto de CLAUDE_COMMANDS
+ * usado por generateClaudeCommands — só o comportamento de sobrescrita difere.
  */
 function generateClaudeCommandsForce(rootDir) {
   const dir = rootDir ? path.join(rootDir, '.claude', 'commands', 'trackfw') : '.claude/commands/trackfw'
-  fs.mkdirSync(dir, { recursive: true })
-
-  const commands = {
-    'adr.md': `Execute o seguinte comando bash: \`trackfw adr new "$ARGUMENTS"\`\n\nSe o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:\n\n\`\`\`\ntrackfw não está instalado. Instale com uma das opções:\n\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n  npm install -g trackfw\n  pip install trackfw\n\`\`\``,
-    'req.md': `Execute o seguinte comando bash: \`trackfw req new "$ARGUMENTS"\`\n\nSe o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:\n\n\`\`\`\ntrackfw não está instalado. Instale com uma das opções:\n\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n  npm install -g trackfw\n  pip install trackfw\n\`\`\``,
-    'validate.md': `Execute o seguinte comando bash: \`trackfw validate\`\n\nSe o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:\n\n\`\`\`\ntrackfw não está instalado. Instale com uma das opções:\n\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n  npm install -g trackfw\n  pip install trackfw\n\`\`\``,
-    'status.md': `Execute o seguinte comando bash: \`trackfw status\`\n\nSe o comando falhar com \`trackfw: command not found\` ou similar, informe ao usuário:\n\n\`\`\`\ntrackfw não está instalado. Instale com uma das opções:\n\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh\n  npm install -g trackfw\n  pip install trackfw\n\`\`\``,
-    'move.md': `Execute o seguinte comando bash: \`trackfw roadmap move $ARGUMENTS\`\n\nO formato esperado é: \`<nome-do-roadmap> <estado>\`\nEstados válidos: \`backlog\`, \`analyzing\`, \`wip\`, \`blocked\`, \`done\`, \`abandoned\`\n\nSe o comando falhar, instale trackfw com:\n  curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh`,
-    'architect.md': `Você é o guia de arquitetura do trackfw. Ajude o usuário a escolher a stack correta e arquitetar a aplicação em linguagem simples, acessível para times não técnicos.\n\n## Passo 1 — Descoberta de Negócio\n\nFaça ao usuário as seguintes perguntas em linguagem simples, uma por vez:\n\n1. "O que sua aplicação vai fazer? Descreva em 2-3 frases como se fosse explicar para alguém de fora da TI."\n2. "Quantas pessoas vão usar esse sistema simultaneamente? (< 10 pessoas / 10-100 pessoas / > 100 pessoas)"\n3. "Esse sistema vai para produção de verdade ou é um protótipo para validar uma ideia?"\n4. "Você precisa de login/autenticação de usuários? (Sim / Não / Não sei)"\n5. "Tem alguma restrição de tecnologia ou preferência da empresa? (ex: só Java, só Microsoft, etc.)"\n\n---\n\n## Passo 2 — Recomendação de Stack\n\nCom base nas respostas, escolha **UM** dos combos pré-validados:\n\n### Combo A — Protótipo Rápido\n**Quando usar:** prototipagem, validação de ideia, até ~10 usuários, sem pressão de produção.\n- **Frontend:** React + Vite\n- **Backend:** FastAPI (Python) ou Express (Node.js)\n- **Banco:** SQLite + SQLAlchemy / Prisma\n- **Auth:** JWT simples quando necessário\n- **Docker:** Dockerfile básico para o backend\n\n### Combo B — Sistema Pequeno/Médio em Produção\n**Quando usar:** sistema real, 10-100 usuários, robustez e manutenibilidade.\n- **Frontend:** Next.js (SSR + rotas prontas)\n- **Backend:** FastAPI (Python) ou NestJS (Node.js)\n- **Banco:** PostgreSQL + ORM (SQLAlchemy / Prisma / TypeORM)\n- **Auth:** OAuth2 com JWT (Supabase Auth ou Auth0)\n- **Docker:** docker-compose com frontend + backend + banco\n\n### Combo C — Enterprise / Java\n**Quando usar:** integração com sistemas corporativos, > 100 usuários, exigência de Java.\n- **Frontend:** Angular\n- **Backend:** Spring Boot\n- **Banco:** PostgreSQL + Hibernate\n- **Auth:** Spring Security + OAuth2 (Keycloak ou Azure AD)\n- **Docker:** docker-compose com todos os serviços\n\nApresente o combo recomendado com explicação simples do motivo.\n\n---\n\n## Passo 3 — Arquitetura em Camadas (explicação simples)\n\nExplique a arquitetura com uma metáfora de negócio:\n\n"Pense na aplicação como um restaurante:\n- **Frontend** = o salão: o que o cliente vê e interage\n- **Backend** = a cozinha: onde as regras de negócio acontecem, nunca exposta diretamente\n- **Banco de dados** = a despensa: onde os dados ficam guardados, acessada só pela cozinha"\n\nReforce as **Architecture Directives** já injetadas no CLAUDE.md deste projeto: separação em 3 camadas sem dados em memória (sempre DB + ORM), auth + Docker + .env desde o dia 1, validação em 2 camadas, contrato OpenAPI antes de codar, wave de segurança em todo roadmap e cobertura mínima de testes (60% protótipo / 80% produção).\n\n---\n\n## Passo 4 — Gerar o ADR de Stack\n\nExecute \`/trackfw:adr\` com o título: \`"Stack e arquitetura em camadas — [nome do projeto]"\`\n\nO ADR deve registrar a stack escolhida (combo e componentes), motivação baseada nas respostas, alternativas descartadas e princípios de arquitetura adotados.\n\n---\n\n## Passo 5 — Próximos Passos\n\nOriente o usuário:\n\n\`\`\`\n✅ Stack definida. Próximos passos:\n\n1. Crie a REQ da primeira feature com /trackfw:req\n2. Gere o roadmap em microlotes com /trackfw:roadmap\n3. Inicie a implementação com /trackfw:implement\n\`\`\``,
-  }
-
-  for (const [filename, content] of Object.entries(commands)) {
-    fs.writeFileSync(path.join(dir, filename), content, 'utf8')
-  }
-  console.log(`  ✓ .claude/commands/trackfw/ (${Object.keys(commands).length} slash commands sobrescritos)`)
+  installClaudeCommandsInner(dir, true)
 }
 
 /**

package/src/generators/roadmap.js

@@ -3,6 +3,7 @@ const fs = require('fs')
 const path = require('path')
 const config = require('../config')
 const { localDateISO } = require('./date')
+const { resolveReqFiles } = require('../validator/index.js')
 
 const VALID_STATES = ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']
 const STATE_ORDER = ['analyzing', 'wip', 'backlog', 'blocked', 'done', 'abandoned']
@@ -251,6 +252,9 @@ function moveRoadmap(name, state) {
 
   appendTransitionLog(logBasename, fromState, state)
   console.log(`✓ moved ${basename} → ${targetDir}`)
+
+  // Sincroniza o roadmap: das REQs que apontem para este roadmap.
+  syncReqReferences(basename, dst, cfg)
 }
 
 /**
@@ -273,6 +277,124 @@ function appendTransitionLog(basename, fromState, toState) {
   } catch (_) {}
 }
 
+/**
+ * extractFrontmatterRoadmap — extrai o valor do campo `roadmap:` SOMENTE do frontmatter.
+ * Retorna null se não encontrado ou se não termina em .md.
+ * Não usa extractRefPath do validator porque este percorre todo o conteúdo (inclusive corpo)
+ * sem distinguir frontmatter de body — geraria falsos positivos em REQs sem roadmap: no FM.
+ */
+function extractFrontmatterRoadmap(content) {
+  const lines = content.split('\n')
+  let inFm = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (i === 0 && line.trim() === '---') { inFm = true; continue }
+    if (inFm && line.trim() === '---') return null // fechou frontmatter sem encontrar
+    if (!inFm) return null // nunca entrou no frontmatter
+    const idx = line.indexOf(':')
+    if (idx === -1) continue
+    if (line.slice(0, idx).trim() !== 'roadmap') continue
+    let val = line.slice(idx + 1).trim()
+    val = val.replace(/^["']|["']$/g, '').trim()
+    if (val.endsWith('.md')) return val
+    return null // roadmap: existe mas sem .md (ex: "" ou slug)
+  }
+  return null
+}
+
+/**
+ * rewriteReqRoadmapRef — reescreve o campo `roadmap:` no frontmatter e a linha `Roadmap:` no
+ * corpo de uma REQ, substituindo oldRef por newRef.
+ * Preserva toda formatação existente (aspas, backticks) via substituição literal de string.
+ */
+function rewriteReqRoadmapRef(content, oldRef, newRef) {
+  const lines = content.split('\n')
+  let inFm = false
+  let fmDone = false
+  const result = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (i === 0 && line.trim() === '---') { inFm = true; result.push(line); continue }
+    if (inFm && line.trim() === '---') { inFm = false; fmDone = true; result.push(line); continue }
+    if (inFm) {
+      const idx = line.indexOf(':')
+      if (idx !== -1 && line.slice(0, idx).trim() === 'roadmap' && line.includes(oldRef)) {
+        result.push(line.replace(oldRef, newRef))
+        continue
+      }
+      result.push(line)
+      continue
+    }
+    if (fmDone) {
+      // No corpo: reescreve linhas `Roadmap:` que contenham oldRef
+      if (line.trim().toLowerCase().startsWith('roadmap:') && line.includes(oldRef)) {
+        result.push(line.replace(oldRef, newRef))
+        continue
+      }
+    }
+    result.push(line)
+  }
+
+  return result.join('\n')
+}
+
+/**
+ * syncReqReferences — após rename bem-sucedido, varre req_dir (flat + by_agent) e reescreve o
+ * frontmatter `roadmap:` e a linha `Roadmap:` do corpo em toda REQ que aponte para o roadmap
+ * movido. Implementa as cinco cardinalidades do contrato:
+ *   zero → no-op silencioso; uma → reescreve; várias → reescreve todas; aponta para outro →
+ *   não toca; já correta → nenhuma escrita (idempotente byte-a-byte).
+ * Erros: diagnóstico em stderr nomeando a REQ; tenta as restantes; exit não-zero ao fim.
+ */
+function syncReqReferences(movedBasename, newRoadmapPath, cfg) {
+  // Ordenação explícita por basename (independente de locale) para garantir saída determinística
+  // independente do filesystem. Desempate por caminho completo quando dois agentes têm REQs de
+  // mesmo basename. Não confiar na ordem do readdirSync — varia entre filesystems.
+  const files = resolveReqFiles(cfg).sort((a, b) => {
+    const ba = path.basename(a)
+    const bb = path.basename(b)
+    if (ba < bb) return -1
+    if (ba > bb) return 1
+    if (a < b) return -1
+    if (a > b) return 1
+    return 0
+  })
+  let anyError = false
+
+  for (const filePath of files) {
+    let content
+    try {
+      content = fs.readFileSync(filePath, 'utf8')
+    } catch (e) {
+      console.error(`trackfw roadmap move: failed to sync ${path.basename(filePath)}: ${e.message}`)
+      anyError = true
+      continue
+    }
+
+    const currentRef = extractFrontmatterRoadmap(content)
+    if (!currentRef) continue
+    if (path.basename(currentRef) !== movedBasename) continue // aponta para outro roadmap
+    if (currentRef === newRoadmapPath) {
+      // Guarda rápida: frontmatter já correto — confirma idempotência com reescrita estrutural
+      const updated = rewriteReqRoadmapRef(content, currentRef, newRoadmapPath)
+      if (updated === content) continue // sem escrita, sem output
+    }
+
+    try {
+      const updated = rewriteReqRoadmapRef(content, currentRef, newRoadmapPath)
+      if (updated === content) continue // nenhuma escrita, nenhum output (idempotência byte-a-byte)
+      fs.writeFileSync(filePath, updated, 'utf8')
+      console.log(`✓ synced ${path.basename(filePath)} → ${newRoadmapPath}`)
+    } catch (e) {
+      console.error(`trackfw roadmap move: failed to sync ${path.basename(filePath)}: ${e.message}`)
+      anyError = true
+    }
+  }
+
+  if (anyError) process.exitCode = 1
+}
+
 /**
  * newRoadmap — cria roadmap em <roadmapDir>/backlog/ROADMAP-YYYY-MM-DD-<slug>.md.
  * Em modo by_agent, usa o primeiro agente configurado.
@@ -524,6 +646,9 @@ module.exports = {
   moveRoadmap,
   rewriteRoadmapStatus,
   appendTransitionLog,
+  extractFrontmatterRoadmap,
+  rewriteReqRoadmapRef,
+  syncReqReferences,
   newRoadmap,
   newRoadmapFromReq,
   stateDir,

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

@@ -24,7 +24,10 @@ Append an entry to `docs/agents-working-context.md` when you start and when you
 Before investigating a bug or unexpected behavior, read `vault/notes/index.md` when it exists and open the related notes. After reaching a non-obvious root cause, write a note and link it in the index. Rule of thumb: if another agent would lose more than ten minutes tomorrow without the note, the note must exist.
 
 ## Git authority
-This is the only role allowed to create branches (`git checkout -b`). Commits from this role are limited to orchestration artifacts: ADRs, REQs, roadmaps, vault notes and the working context file. Never commit product code. Push to the working branch, and open a pull request only when the user explicitly asks. Never merge.
+`trackfw_architect` is the **only** role with Git authority in this project. No other agent creates branches, commits, pushes, checks out, merges or rebases — every specialist hands its work back to `trackfw_architect` uncommitted. This role: creates the branch (`git checkout -b`) before any handoff; audits the full diff produced by specialists against the assigned scope; performs every commit, including orchestration artifacts (ADRs, REQs, roadmaps, vault notes, the working context file) and the product code produced by specialists once audited; pushes to the working branch; and suggests opening a pull request, opening it only when the user explicitly asks. Never merge.
+
+## Barrier protocol
+Before releasing the next wave: invoke the `code-quality` and `security` roles whenever the change warrants their review (new code paths, dependencies, permissions, secrets, parsers, or attack surface); block the next wave on any failed check and dispatch a corrective microbatch to the owning role instead of proceeding; audit the diff and re-run the wave's gates before performing any commit. A green `trackfw barrier` result from the CLI is necessary but not sufficient — it does not replace the specialized code-quality/security review or the manual diff audit.
 
 ## Parallelization
 Analyze real dependencies between microbatches before assigning work. Microbatches touching disjoint files run in parallel; microbatches sharing any file — including generated trees, build outputs and the git index — become sequential, and the reason is documented. Put an explicit barrier between waves. Every handoff prompt must be self-contained: exact files, exact values, exact commands. Never let two agents edit the same file at the same time.

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

@@ -26,11 +26,11 @@ Before investigating a bug or unexpected behavior, read `vault/notes/index.md` w
 ## Governance prerequisite
 Do not edit code without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
 
-## Git boundary
-You must not create branches and must not open pull requests. Commit only on the branch the orchestrator already created, using Conventional Commits, with no agent name suffix and no AI model trailer.
+## Git authority
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
 
 ## Microbatch completion protocol
-In order: build, tests, project gate, `trackfw validate`, commit, push, then update the microbatch status in the roadmap. Report the exact command output as evidence, not a summary of it.
+In order: build, tests, project gate, `trackfw validate`, then report the exact command output as evidence and hand the microbatch back to `trackfw_architect` for audit and commit. Update the microbatch status in the roadmap only after the orchestrator's audit passes.
 
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.

package/src/integrations/assets/agents/code-quality.md

@@ -29,6 +29,9 @@ Do not edit code without a requirement and a roadmap already in the `wip` state.
 ## Reporting boundary
 You do not modify code. Report findings ordered by severity, each with concrete evidence (file, line, and the observed behavior), and hand off the fix to the role that owns the code. Never weaken a control, a test or a permission to make something pass.
 
+## Git authority
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
+
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.
 

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

@@ -26,11 +26,11 @@ Before investigating a bug or unexpected behavior, read `vault/notes/index.md` w
 ## Governance prerequisite
 Do not edit code without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
 
-## Git boundary
-You must not create branches and must not open pull requests. Commit only on the branch the orchestrator already created, using Conventional Commits, with no agent name suffix and no AI model trailer.
+## Git authority
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
 
 ## Microbatch completion protocol
-In order: build, tests, project gate, `trackfw validate`, commit, push, then update the microbatch status in the roadmap. Report the exact command output as evidence, not a summary of it.
+In order: build, tests, project gate, `trackfw validate`, then report the exact command output as evidence and hand the microbatch back to `trackfw_architect` for audit and commit. Update the microbatch status in the roadmap only after the orchestrator's audit passes.
 
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.

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

@@ -26,11 +26,11 @@ Before investigating a bug or unexpected behavior, read `vault/notes/index.md` w
 ## Governance prerequisite
 Do not edit code without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
 
-## Git boundary
-You must not create branches and must not open pull requests. Commit only on the branch the orchestrator already created, using Conventional Commits, with no agent name suffix and no AI model trailer.
+## Git authority
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
 
 ## Microbatch completion protocol
-In order: build, tests, project gate, `trackfw validate`, commit, push, then update the microbatch status in the roadmap. Report the exact command output as evidence, not a summary of it.
+In order: build, tests, project gate, `trackfw validate`, then report the exact command output as evidence and hand the microbatch back to `trackfw_architect` for audit and commit. Update the microbatch status in the roadmap only after the orchestrator's audit passes.
 
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.

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

@@ -26,11 +26,11 @@ Before investigating a bug or unexpected behavior, read `vault/notes/index.md` w
 ## Governance prerequisite
 Do not edit code without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
 
-## Git boundary
-You must not create branches and must not open pull requests. Commit only on the branch the orchestrator already created, using Conventional Commits, with no agent name suffix and no AI model trailer.
+## Git authority
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
 
 ## Microbatch completion protocol
-In order: build, tests, project gate, `trackfw validate`, commit, push, then update the microbatch status in the roadmap. Report the exact command output as evidence, not a summary of it.
+In order: build, tests, project gate, `trackfw validate`, then report the exact command output as evidence and hand the microbatch back to `trackfw_architect` for audit and commit. Update the microbatch status in the roadmap only after the orchestrator's audit passes.
 
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.

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

@@ -28,11 +28,11 @@ Before investigating a bug or unexpected behavior, read `vault/notes/index.md` w
 ## Governance prerequisite
 Do not edit code without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
 
-## Git boundary
-You must not create branches and must not open pull requests. Commit only on the branch the orchestrator already created, using Conventional Commits, with no agent name suffix and no AI model trailer.
+## Git authority
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
 
 ## Microbatch completion protocol
-In order: build, tests, project gate, `trackfw validate`, commit, push, then update the microbatch status in the roadmap. Report the exact command output as evidence, not a summary of it.
+In order: build, tests, project gate, `trackfw validate`, then report the exact command output as evidence and hand the microbatch back to `trackfw_architect` for audit and commit. Update the microbatch status in the roadmap only after the orchestrator's audit passes.
 
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.

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

@@ -28,11 +28,11 @@ Before investigating a bug or unexpected behavior, read `vault/notes/index.md` w
 ## Governance prerequisite
 Do not edit code without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
 
-## Git boundary
-You must not create branches and must not open pull requests. Commit only on the branch the orchestrator already created, using Conventional Commits, with no agent name suffix and no AI model trailer.
+## Git authority
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
 
 ## Microbatch completion protocol
-In order: build, tests, project gate, `trackfw validate`, commit, push, then update the microbatch status in the roadmap. Report the exact command output as evidence, not a summary of it.
+In order: build, tests, project gate, `trackfw validate`, then report the exact command output as evidence and hand the microbatch back to `trackfw_architect` for audit and commit. Update the microbatch status in the roadmap only after the orchestrator's audit passes.
 
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.

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

@@ -26,11 +26,11 @@ Before investigating a bug or unexpected behavior, read `vault/notes/index.md` w
 ## Governance prerequisite
 Do not edit code without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
 
-## Git boundary
-You must not create branches and must not open pull requests. Commit only on the branch the orchestrator already created, using Conventional Commits, with no agent name suffix and no AI model trailer.
+## Git authority
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
 
 ## Microbatch completion protocol
-In order: build, tests, project gate, `trackfw validate`, commit, push, then update the microbatch status in the roadmap. Report the exact command output as evidence, not a summary of it.
+In order: build, tests, project gate, `trackfw validate`, then report the exact command output as evidence and hand the microbatch back to `trackfw_architect` for audit and commit. Update the microbatch status in the roadmap only after the orchestrator's audit passes.
 
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.

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

@@ -29,6 +29,9 @@ Do not edit code without a requirement and a roadmap already in the `wip` state.
 ## Reporting boundary
 You do not modify code. Report findings ordered by severity, each with concrete evidence (file, line, and the observed behavior), and hand off the fix to the role that owns the code. Never weaken a control, a test or a permission to make something pass.
 
+## Git authority
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
+
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.
 

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

@@ -26,11 +26,11 @@ Before investigating a bug or unexpected behavior, read `vault/notes/index.md` w
 ## Governance prerequisite
 Do not edit code without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
 
-## Git boundary
-You must not create branches and must not open pull requests. Commit only on the branch the orchestrator already created, using Conventional Commits, with no agent name suffix and no AI model trailer.
+## Git authority
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
 
 ## Microbatch completion protocol
-In order: build, tests, project gate, `trackfw validate`, commit, push, then update the microbatch status in the roadmap. Report the exact command output as evidence, not a summary of it.
+In order: build, tests, project gate, `trackfw validate`, then report the exact command output as evidence and hand the microbatch back to `trackfw_architect` for audit and commit. Update the microbatch status in the roadmap only after the orchestrator's audit passes.
 
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.

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

@@ -29,6 +29,9 @@ Do not edit code without a requirement and a roadmap already in the `wip` state.
 ## Reporting boundary
 You do not modify code. Report findings ordered by severity, each with concrete evidence (file, line, and the observed behavior), and hand off the fix to the role that owns the code. Never weaken a control, a test or a permission to make something pass.
 
+## Git authority
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
+
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.