trackfw 4.0.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "4.0.0",
+  "version": "5.0.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.",
   "keywords": [
     "cli",

package/src/commands/barrier.js

@@ -39,38 +39,65 @@ function resolveRoadmapFile(cfg, roadmapArg) {
   throw new UsageError(`roadmap "${roadmapArg}" not found in wip/ nor done/ under ${cfg.roadmapDir}`)
 }
 
+// ────────────────────────────────────────────────────────────────────────────
+// Wave label grammar (pinned by docs/cli-parity.md, "Wave label grammar" section)
+// ────────────────────────────────────────────────────────────────────────────
+
+// Scan regex (mirrors Go's waveHeadingRe): catches any "## Wave <token> " line.
+// The trailing space is part of rule 1 — a heading whose label touches EOL is not
+// recognised as a wave heading (neither valid nor malformed).
+const WAVE_SCAN_RE = /^## Wave (\S+) /
+
+// Grammar: <integer>[-<suffix>] where integer >= 1 and suffix is [a-z0-9]+ (lowercase).
+// Valid: 1, 2, 2-bis, 2-hotfix, 10-a2.
+// Invalid: X, 2-BIS, -bis, 2-, 2-bis-ter, 0.
+const WAVE_LABEL_RE = /^(\d+)(?:-([a-z0-9]+))?$/
+
+// isValidWaveLabel returns true iff token matches the grammar above.
+// Exported so unit tests can assert the full table of valid/invalid examples.
+function isValidWaveLabel(token) {
+  const m = WAVE_LABEL_RE.exec(String(token))
+  if (!m) return false
+  return parseInt(m[1], 10) >= 1
+}
+
 // ────────────────────────────────────────────────────────────────────────────
 // Roadmap parsing rules (string-level, see docs/cli-parity.md)
 // ────────────────────────────────────────────────────────────────────────────
 
-// findWave locates the `## Wave <n> ` heading matching waveNumber and returns its
-// line range [startLine, endLine) within `lines`. Throws UsageError naming the wave
-// number and the resolved roadmap basename when not found (pinned literally by
-// docs/cli-parity.md), or naming the offending line number for a malformed heading.
-// roadmapBasename is optional so existing unit tests that only exercise parsing can
-// omit it; the CLI path always supplies it.
-function findWave(lines, waveNumber, roadmapBasename) {
-  let startLine = -1
+// findWave locates the `## Wave <label> ` heading matching waveLabel and returns its
+// line range [startLine, endLine) within `lines`. Performs a full pre-pass over all
+// wave headings (mirroring Go's parseWaves): throws UsageError for the first malformed
+// heading regardless of position — this ensures a typo like `## Wave X — ...` aborts
+// the entire document (ADR decision 16, non-vacuity). Throws UsageError naming the
+// wave label and the resolved roadmap basename when not found (pinned literally by
+// docs/cli-parity.md). roadmapBasename is optional so unit tests that only exercise
+// parsing can omit it; the CLI path always supplies it.
+function findWave(lines, waveLabel, roadmapBasename) {
+  // Pre-pass: validate ALL wave headings and collect them.
+  // Abort immediately on the first malformed heading — this is intentional and
+  // mirrors Go's parseWaves() full-scan approach (ADR decision 16).
+  const waves = []
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-    const attempt = /^## Wave (\S+)/.exec(line)
+    const attempt = WAVE_SCAN_RE.exec(lines[i])
     if (!attempt) continue
-    if (!/^\d+$/.test(attempt[1])) {
-      throw new UsageError(`malformed wave heading at line ${i + 1}: "${line}"`)
+    const token = attempt[1]
+    if (!isValidWaveLabel(token)) {
+      throw new UsageError(`malformed wave heading at line ${i + 1}: "${token}" is not a valid wave label`)
     }
-    if (parseInt(attempt[1], 10) === waveNumber) {
-      startLine = i
-      break
+    let endLine = lines.length
+    for (let j = i + 1; j < lines.length; j++) {
+      if (/^## /.test(lines[j])) { endLine = j; break }
     }
+    waves.push({ label: token, startLine: i, endLine })
   }
-  if (startLine === -1) {
-    throw new UsageError(`wave ${waveNumber} not found in roadmap "${roadmapBasename}"`)
-  }
-  let endLine = lines.length
-  for (let j = startLine + 1; j < lines.length; j++) {
-    if (/^## /.test(lines[j])) { endLine = j; break }
+
+  // Find the requested wave by exact label match (no prefix/fuzzy matching).
+  const wave = waves.find(w => w.label === String(waveLabel))
+  if (!wave) {
+    throw new UsageError(`wave ${waveLabel} not found in roadmap "${roadmapBasename}"`)
   }
-  return { startLine, endLine }
+  return { startLine: wave.startLine, endLine: wave.endLine }
 }
 
 // findMLs locates every `### ML-` heading inside [startLine, endLine) and returns
@@ -166,7 +193,7 @@ function parseGates(lines, startLine, endLine) {
 // Checks (fixed evaluation order: mls_complete, acceptance_evidence, gates, validate)
 // ────────────────────────────────────────────────────────────────────────────
 
-function evalMlsComplete(mls, waveNumber) {
+function evalMlsComplete(mls, waveLabel) {
   const evidence = []
   const failures = []
   for (const ml of mls) {
@@ -176,7 +203,7 @@ function evalMlsComplete(mls, waveNumber) {
   }
   const status = mls.length > 0 && failures.length === 0 ? 'passed' : 'blocked'
   // Pinned literally by docs/cli-parity.md ("Wave contains zero MLs" case).
-  if (mls.length === 0) failures.push(`wave ${waveNumber}: no ML found`)
+  if (mls.length === 0) failures.push(`wave ${waveLabel}: no ML found`)
   return { name: 'mls_complete', status, evidence, failures }
 }
 
@@ -280,10 +307,10 @@ async function runBarrier(roadmapArg, waveOption, jsonOutput) {
   if (waveOption === undefined || waveOption === null || String(waveOption).trim() === '') {
     throw new UsageError('--wave is required')
   }
-  if (!/^\d+$/.test(String(waveOption).trim()) || parseInt(waveOption, 10) < 1) {
-    throw new UsageError(`invalid --wave value: "${waveOption}" (must be an integer >= 1)`)
+  const waveLabel = String(waveOption).trim()
+  if (!isValidWaveLabel(waveLabel)) {
+    throw new UsageError(`invalid --wave "${waveOption}" — not a valid wave label`)
   }
-  const waveNumber = parseInt(waveOption, 10)
 
   const cfg = config.load()
   const resolved = resolveRoadmapFile(cfg, roadmapArg)
@@ -291,18 +318,18 @@ async function runBarrier(roadmapArg, waveOption, jsonOutput) {
   const lines = content.split('\n')
 
   const startedAt = new Date()
-  const wave = findWave(lines, waveNumber, resolved.basename)
+  const wave = findWave(lines, waveLabel, resolved.basename)
   const mls = findMLs(lines, wave.startLine, wave.endLine)
   const gates = parseGates(lines, wave.startLine, wave.endLine)
 
   const checks = []
-  checks.push(evalMlsComplete(mls, waveNumber))
+  checks.push(evalMlsComplete(mls, waveLabel))
   checks.push(evalAcceptanceEvidence(mls))
   checks.push(evalGates(gates.commands, process.cwd()))
   checks.push(await evalValidate())
   const finishedAt = new Date()
 
-  const doc = buildDoc(resolved.basename, waveNumber, checks, startedAt, finishedAt)
+  const doc = buildDoc(resolved.basename, waveLabel, checks, startedAt, finishedAt)
 
   if (jsonOutput) {
     console.log(JSON.stringify(doc, null, 2))
@@ -322,7 +349,7 @@ function createBarrierCommand() {
       'declared in a roadmap.'
     )
     .argument('<roadmap>', 'Roadmap basename, with or without .md')
-    .option('--wave <n>', 'Wave number to evaluate (integer >= 1)')
+    .option('--wave <label>', 'Wave label to evaluate (e.g. 1, 2-bis, 2-hotfix)')
     .option('--json', 'Emit the result document as JSON instead of a text report')
     .action(async (roadmapArg, options) => {
       try {
@@ -344,6 +371,7 @@ function createBarrierCommand() {
 
 module.exports = createBarrierCommand()
 module.exports.UsageError = UsageError
+module.exports.isValidWaveLabel = isValidWaveLabel
 module.exports.resolveRoadmapFile = resolveRoadmapFile
 module.exports.findWave = findWave
 module.exports.findMLs = findMLs

package/src/commands/init.js

@@ -61,9 +61,12 @@ cmd.action(async (options, command) => {
     const supported = new Set(['claude', 'codex', 'gemini', 'antigravity', 'cursor', 'copilot', 'windsurf', 'amazonq', 'kiro'])
     // Sem TTY, o escopo nunca é perguntado: default `global` (ADR D1/D4).
     const scope = await resolveScope({}, { interactive: false })
+    const makeOnSkip = () => (_destination, reason) => {
+      process.stderr.write(`${reason}\n`)
+    }
     for (const tool of aiTools) {
       if (!supported.has(tool)) throw new Error(`Unsupported AI tool: ${tool}`)
-      await generators.installIntegrationTarget(tool, process.cwd(), scope)
+      await generators.installIntegrationTarget(tool, process.cwd(), scope, { onSkip: makeOnSkip() })
     }
     console.log(`\n${t('init.success')}`)
     require('../generators/init').printArchitectNextSteps(process.cwd())
@@ -277,7 +280,12 @@ cmd.action(async (options, command) => {
   const cfg = { projectName, projectType, frontend, backend, backendFramework, pkgManager, hooks, ci, forge: forgeValue || '', requireReqInCommit }
   await generators.scaffold(cfg)
 
-  for (const tool of (aiTools || [])) await generators.installIntegrationTarget(tool, process.cwd(), scope)
+  for (const tool of (aiTools || [])) {
+    const onSkip = (_destination, reason) => {
+      process.stderr.write(`${reason}\n`)
+    }
+    await generators.installIntegrationTarget(tool, process.cwd(), scope, { onSkip })
+  }
 
   console.log(`\n${t('init.success')}`)
   require('../generators/init').printArchitectNextSteps(process.cwd())

package/src/commands/integrations.js

@@ -183,6 +183,15 @@ function createLifecycleCommand(kind) {
       // operações de mutação (install/update/uninstall) e fora de --json.
       if (mutation) printResolvedDestinations(kind, options)
 
+      // Ligar onSkip: aviso em stderr por artefato outdated+owned pulado pelo
+      // preflight de install (contrato: docs/cli-parity.md, seção "install
+      // sobre artefato gerenciado desatualizado — skip, não erro fatal").
+      if (mutation) {
+        options.onSkip = (_destination, reason) => {
+          process.stderr.write(`${reason}\n`)
+        }
+      }
+
       const output = execute(kind, operation, options)
       console.log(options.json ? JSON.stringify(output) : human(output))
     })

package/src/generators/init.js

@@ -1217,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().

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/index.js

@@ -101,7 +101,7 @@ function execute(kind, operation, options = {}, roots = {}) {
   const homeRoot = roots.homeRoot || os.homedir()
   const identityConfig = options.identity !== undefined ? options.identity : identityStore.load(homeRoot)
   const plans = buildPlans(kind, { ...options, identity: identityConfig })
-  const manager = new IntegrationManager(roots)
+  const manager = new IntegrationManager(roots, { onSkip: options.onSkip })
   let statuses
   if (operation === 'list') statuses = manager.inspect(plans)
   else if (operation === 'install') statuses = manager.install(plans, { force: options.force })

package/src/integrations/manager.js

@@ -6,6 +6,7 @@ const os = require('node:os')
 const path = require('node:path')
 
 const { frontmatterName } = require('./render')
+const { tildeify } = require('../lib/update-engine')
 
 const SCHEMA_VERSION = 1
 const sha256 = content => crypto.createHash('sha256').update(content).digest('hex')
@@ -13,8 +14,9 @@ const claimKey = claim => [claim.target, claim.surface, claim.scope, claim.kind,
 const cleanClaim = claim => ({ target: claim.target, surface: claim.surface, scope: claim.scope, kind: claim.kind, item: claim.item })
 
 class IntegrationManager {
-  constructor({ projectRoot = process.cwd(), homeRoot = os.homedir() } = {}) {
+  constructor({ projectRoot = process.cwd(), homeRoot = os.homedir() } = {}, { onSkip } = {}) {
     this.roots = { project: path.resolve(projectRoot), global: path.resolve(homeRoot) }
+    this.onSkip = onSkip
   }
 
   manifestPath(scope) { return path.join(this.roots[scope], '.trackfw', 'integrations-manifest.json') }
@@ -127,17 +129,33 @@ class IntegrationManager {
     const manifests = new Map()
     for (const { plan } of resolved) if (!manifests.has(plan.claim.scope)) manifests.set(plan.claim.scope, this.loadManifest(plan.claim.scope))
     const desiredByFile = new Map()
+    const skippedFiles = new Set()
     for (const item of resolved) {
       const desired = sha256(item.plan.content)
       if (operation !== 'uninstall' && desiredByFile.has(item.file) && desiredByFile.get(item.file) !== desired) throw new Error(`Conflicting content planned for: ${item.file}`)
       desiredByFile.set(item.file, desired)
-      this.preflight(operation, item, manifests.get(item.plan.claim.scope), force)
+      const skip = this.preflight(operation, item, manifests.get(item.plan.claim.scope), force)
+      if (skip) {
+        skippedFiles.add(item.file)
+        if (typeof this.onSkip === 'function') {
+          // O manager compõe a linha completa e passa tilde-abreviado como
+          // destination (contrato: docs/cli-parity.md, "Valor de cada
+          // parâmetro — pinado"). A remediação é derivada de
+          // plan.claim.scope por artefato, nunca de inferência sobre o
+          // caminho renderizado.
+          const abbrev = this.tildeAbbrev(item.file, item.plan.claim.scope)
+          const remediation = item.plan.claim.scope === 'global' ? 'trackfw update harness' : 'trackfw update'
+          const reason = `warning: skipping outdated artifact ${abbrev}; run '${remediation}' to refresh it`
+          this.onSkip(abbrev, reason)
+        }
+      }
     }
+    const active = resolved.filter(item => !skippedFiles.has(item.file))
     const snapshots = new Map()
-    for (const item of resolved) this.snapshot(snapshots, item.file)
+    for (const item of active) this.snapshot(snapshots, item.file)
     for (const scope of manifests.keys()) this.snapshot(snapshots, this.manifestPath(scope))
     try {
-      for (const item of resolved) this.apply(operation, item, manifests.get(item.plan.claim.scope), force)
+      for (const item of active) this.apply(operation, item, manifests.get(item.plan.claim.scope), force)
       for (const [scope, manifest] of [...manifests].sort(([a], [b]) => a.localeCompare(b))) this.saveManifest(scope, manifest)
     } catch (error) {
       this.rollback(snapshots)
@@ -153,13 +171,14 @@ class IntegrationManager {
     const owned = Boolean(record && record.claims.some(claim => claimKey(claim) === claimKey(plan.claim)))
     if (operation === 'install') {
       if (status.state === 'modified' && !force) throw new Error(`Artifact is modified; use --force: ${file}`)
-      if (status.state === 'outdated' && owned && !force) throw new Error(`Artifact is outdated; use update: ${file}`)
+      if (status.state === 'outdated' && owned && !force) return true // skip: bytes preserved, batch continues
     } else if (operation === 'update') {
       if (!owned && status.state === 'modified') throw new Error(`Unmanaged artifact does not match a trackfw template: ${file}`)
       if (status.state === 'modified' && !force) throw new Error(`Artifact is modified; use --force: ${file}`)
     } else if (operation === 'uninstall' && owned && status.state === 'modified' && !force) {
       throw new Error(`Artifact is modified; use --force: ${file}`)
     }
+    return false
   }
 
   // detectNameCollision protege contra dois artefatos de agente gerenciados
@@ -273,6 +292,16 @@ class IntegrationManager {
     }
   }
 
+  // tildeAbbrev — retorna o caminho de exibição abreviado para uso em mensagens
+  // de aviso de skip. Espelha internal/integrations/manager.go:tildeAbbrev.
+  // - scope global: substitui homeRoot por '~' (via tildeify, com salvaguarda
+  //   de barra dupla corrigida no ML-6H).
+  // - scope de projeto: caminho relativo ao projectRoot, sem './' prefixo.
+  tildeAbbrev(file, scope) {
+    if (scope === 'global') return tildeify(this.roots.global, file)
+    return path.relative(this.roots.project, file)
+  }
+
   cleanEmpty(directory, root) {
     while (directory !== root) {
       const rel = path.relative(root, directory)